기술 문서 사이트로 Docusaurus 활용하기

핵심 내용

• 기술 문서 사이트를 위한 팀 공용 SSG로 Docusaurus를 선정한 배경과 기준 정리
• 문서 엔지니어링 관점에서 docs as code, 기본 기능, 확장성, 익숙한 JavaScript/React 생태계가 선택 기준
• Docusaurus의 MDX, 플러그인, 테마 기능을 활용해 문서용 기능과 UI를 함께 커스터마이징한 사례 소개

구조와 흐름

• 줄 바꿈 테이블, 용어집, API 문서화를 각각 컴포넌트와 YAML 데이터, 전역 데이터로 분리해 구현
• Markdown의 한계를 보완하면서도 문서 작성자에게는 비교적 단순한 작성 방식 유지
• 데이터와 뷰를 분리해 대량 문서 수정과 재정렬 비용을 줄이는 방향으로 설계

적용해볼 점

• 팀 공용 문서 사이트에서는 SSG 기본 기능과 커스터마이징 가능성을 함께 검토할 필요
• 문서 내용이 많고 구조가 자주 바뀌는 경우, Markdown 단독보다 데이터 기반 렌더링이 유리
• 도구 선택 전 i18n, 마크업 지원, 파일 관리 방식 같은 기본 메커니즘 확인 필요