05_기술 블로그 개설

개요

---

개발 과정에서 달마다 글을 블로그에 작성하기로 했다.

Notion 글 작성까지는 확정이였으나, 퍼블릭 배포를 어떻게 할지가 고민이였다.

여러 후보 (Velog, Tistory) 가 있어서 동시에 해보다가, docusaurus 를 선택하였다.

docusaurus 는 Meta 에서 만든 오픈소스 프로젝트로, 다양한 기업에서 사용하고 있는 SSG (static site generator) 이다.

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

그 외에 Plugin, Routing, SSG (Static Site Generation), Client Architecture 까지 있다.

아래에 참고 링크가 있다.

참고 링크 : https://docusaurus.io/docs/advanced

---

Notion to Docusaurus 동기화

작성 글 퍼블릭 배포할 예정인 우리는, 아래 과정을 거쳐 동기화했다.

1. Notion 글 작성

• 협업 시 Notion 을 오랫동안 써왔기에, 일단 생각나는 대로 적기 시작했다

2. docusaurus config 설정

• 공식 문서 참고 추천한다 (https://docusaurus.io/ko/docs/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 Token 발급 / 데이터베이스 별 ID 확인 필요하다

  NOTION_TOKEN= 
  ...
  NOTION_RELEASE=
  NOTION_INSTALL=

• notion_to_md.py 로, Notion 내용이 서버에 나타난다

4. workflow 동기화

• build 와 deploy 과정으로 분할

  • build: main branch 코드 읽기, md 파일 → 정적 파일 (HTML/CSS/JS) 로 변환

  • deploy: doc.scenemaker.solbox.com 반영

    name: Deploy to GitHub Pages
    
    jobs:
      build:
         ...
    
          - name: Install dependencies
            run: npm ci
    
          - name: Build (production, all locales)
            run: npm run build
    
      deploy:
        name: Deploy
        needs: build
        runs-on: ubuntu-latest
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
    

• Github Action 결과

---

동기화 결과

Notion 에서 보는 것과 완전 똑같이 나오는 것을 목표로 하였다.

생각보다 작업 시간이 많이 소요된 Docusaurus 이전 작업이였다.

기본적인 레이아웃부터, 테마 및 SEO 작업, 무엇보다 md 파일 작성이 가장 오래 걸렸다.

그래도 어느 정도 틀을 구축하니 이후엔 속도가 붙기 시작하였으며, 매력적인 툴이라고 생각한다.

다들 한번씩은 해보기를 추천한다.

---