본문으로 건너뛰기

05_기술 블로그 개설

· 약 4분
sbin
sbin
SceneMakerAI 팀

들어가며​

이 블로그는 오픈소스 AI 기술로 방송 콘텐츠를 재가공하는 솔박스(Solbox Inc.) SceneMakerAI 프로젝트의 공식 기술 블로그 다.

개발 과정에서, 달마다 글을 블로그에 작성하기로 했다. Notion 글 작성까지는 확정이었으나, 퍼블릭 배포를 어떻게 할지가 고민이었다. 여러 후보(Velog, Tistory)를 두고 동시에 테스트해 보다가, 최종적으로 Docusaurus 를 선택했다.

image

Docusaurus는 Meta에서 만든 오픈소스 프로젝트로, 다양한 기업에서 사용하고 있는 SSG(Static Site Generator)다. 공식 문서도 잘 갖춰져 있고 커뮤니티가 활발하고 , 무엇보다 위와 같은 깊이 있는 아키텍처까지 제공한다는 점에서 신뢰가 갔다.

플랫폼을 선정할 때 고민했던 비교 내용은 다음과 같다.

플랫폼장점단점선택 여부
Velog개설이 쉽고 개발자 접근성이 좋음커스텀 테마나 문서 구조화에 한계가 있음보류
Tistory스킨 커스텀이 가능하고 대중적임마크다운 지원이 아쉽고 코드로 관리하기 어려움보류
Docusaurus코드로 사이트를 완전 소유 할 수 있고, 문서와 블로그를 통합 하여 구조화 가능. Notion 연동 자동화가 매우 유리 함초기 설정 및 배포 파이프라인 구축 공수가 큼최종 선택

공식 문서도 있고, 커뮤니티가 활달하며, 아래와 같은 아키텍처까지 볼 수 있다는 것에 놀랐다.

image

그 외에 Plugin, Routing, SSG (Static Site Generation), Client Architecture 까지 있다. (참고 링크: Docusaurus Advanced )

Notion to Docusaurus 동기화​

작성한 글을 퍼블릭으로 배포하기 위해, 아래 과정을 거쳐 동기화 파이프라인을 구축했다.

1. Notion 글 작성​
  • 협업 시 Notion 을 오랫동안 써왔으며, 블로그 글을 원래 하던대로 일단 사용하였다.

실제 팀 내부에서 기술 블로그 초안을 작성하는 Notion 워크스페이스 화면

image

2. docusaurus config 설정​
  • 자세한 CLI 설정은 공식 문서(Docusaurus CLI )를 참고하는 것을 추천한다. docusaurus.config.ts 파일에 우리의 URL과 GitHub 페이지를 연결했다.
const config: Config = {
  title: 'SceneMakerAI',
  tagline: '오픈소스 AI로 방송 콘텐츠를 재가공하다 — SceneMakerAI 기술 블로그 · 문서',

  ... 
            sameAs: ['https://github.com/SceneMakerAI'],
            parentOrganization: { '@type': 'Organization', name: '솔박스(Solbox Inc.)' },
          },
          {
            '@type': 'WebSite',
            name: 'SceneMakerAI Docs',
            url: 'https://doc.scenemaker.solbox.com',
          },
        ],
      }),
    },
3. Notion-to-md 복사​
  • Notion API를 사용하기 위해 Token 발급 및 데이터베이스별 ID 확인이 필요하다.
NOTION_TOKEN= 
...
NOTION_RELEASE=
NOTION_INSTALL=
  • notion_to_md.py 스크립트를 사용하여 Notion 내용이 빌드 서버에 마크다운 형태로 나타나게 구축했다.

image

4. workflow 동기화​
  • GitHub Actions를 활용해 빌드(Build)와 배포(Deploy) 과정을 분할하여 CI 설정을 완료했다.

    • Build : main branch 코드를 읽고, 변환된 md 파일을 정적 파일(HTML/CSS/JS)로 빌드 (npm ci 후 npm run build )

    • Deploy : 빌드된 정적 파일을 운영 도메인(doc.scenemaker.solbox.com )에 자동 반영

    • 성공적으로 통과한 GitHub Actions의 빌드 및 배포 워크플로우 화면

image

동기화 결과​

우리의 핵심 목표는 Notion에서 보는 화면 구성을 Notion 원본과 동일하게 웹에 구현하는 것이었다.

image

Notion 레이아웃이 Docusaurus 테마로 완벽하게 변환되어 배포된 결과물

마무리​

이 과정이 순탄치만은 않았는데, 생각보다 작업 시간이 많이 소요된 Docusaurus 이전 작업이었다.

특히 가장 크게 막혔던 부분은 Notion to md, md to Notion 양방향 동기화 를 예외 없이 매끄럽게 처리하는 단계였다.

Notion 고유의 블록 스타일이나 커스텀 토글, 이미지 임베드 경로를 마크다운 파일로 깨지지 않게 변환하고,

이를 다시 Docusaurus의 테마 및 SEO 최적화 레이아웃에 완벽히 맞추는 싱크 작업에서 수많은 렌더링 에러를 겪으며 꽤나 삽질을 했다.

그래도 어느 정도 우리만의 자동화 틀을 구축하고 나니 이후에는 글만 써도 자동으로 배포되어 속도가 붙기 시작했다. 고생한 보람이 있는 정말 매력적인 툴이다.

다음 글 예고​

이제 완벽한 기술 블로그 인프라가 갖춰졌으니, 본격적으로 SceneMakerAI의 핵심 기술들을 공유하려 한다. 다음 글에서는 방송 도메인에 LLM을 최적화하여 적용했던 'Qwen3.6 방송 도메인 적용기'를 상세히 다룰 예정이니 많은 기대 부탁한다.

본 글은 과학기술정보통신부·정보통신산업진흥원 「2026년 오픈소스 AI·SW 개발·활용 지원사업」의 지원으로 수행된 연구 결과입니다.