[React] TypeDoc + Docusaurus 기반 API 문서 시스템 구축하기

TypeScript 프로젝트의 API 문서를 자동으로 생성하고, 가독성 좋은 정적 사이트로 배포하기 위해 TypeDoc과 Docusaurus를 연동한 구축 과정을 기록합니다.

✅ 목적

• JSDoc 기반 API 문서를 자동 생성
• Markdown으로 변환
• Docusaurus로 정적 사이트 구성
• 실제 서비스에 사용할 수 있는 문서 UI 제공

---

🧱 전체 구성 흐름

1. TypeDoc: TypeScript 코드 → Markdown 문서
2. Docusaurus: Markdown 문서 → 정적 웹사이트

---

🔧 사전 환경

• Node.js: v16.20.2
• TypeScript: ^4.7.4
• Docusaurus: 2.3.1
• TypeDoc: ^0.25.x
• typedoc-plugin-markdown: 최신 안정 버전

---

📦 패키지 설치

npm install --save-dev typedoc typedoc-plugin-markdown
npm install @docusaurus/core @docusaurus/preset-classic react react-dom

---

📁 TypeDoc 설정 (typedoc.json)

{
  "entryPoints": ["./src/core"],
  "entryPointStrategy": "expand",
  "out": "./docs-site/docs/api",
  "plugin": ["typedoc-plugin-markdown"],
  "readme": "none",
  "exclude": [
    "**/__tests__/**",
    "**/test__/**",
    "**/__mock__/**",
    "**/*.test.ts",
    "**/*.spec.ts"
  ],
  "hidePageTitle": true,
  "hideBreadcrumbs": true,
  "categorizeByGroup": false,
  "sort": ["source-order"]
}

---

⚙️ Docusaurus 설정

docusaurus.config.js

docs: {
  sidebarPath: require.resolve('./sidebars.js'),
  editUrl: undefined
},
blog: false, // 블로그 기능 제거

sidebars.js

module.exports = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'API Reference',
      items: [{ type: 'autogenerated', dirName: 'api' }]
    }
  ]
};

---

🧪 문제 해결 요약

문제	해결 방법
undici 에러	blog: false로 블로그 플러그인 제거
readme/readme 경로 중복	"readme": "none" 설정
1뎁스 README 제거	"exclude": ["**/index.ts"] 추가
TypeDoc 결과가 안 보임	entryPointStrategy: "expand"로 설정

---

💡 실전 팁

• typedoc은 코드 구조 그대로 문서를 뽑고,
• docusaurus는 그 문서를 예쁘게 보여주는 역할
• API가 많거나 경로가 깊으면 성능 이슈 있음 → src 일부만 지정해서 관리

---

📜 마무리

TypeDoc과 Docusaurus를 연동하면 코드 기반 API 문서를 자동으로 생성하고, 팀 전체가 공유 가능한 수준 높은 개발 문서를 구축할 수 있습니다.

향후 CI/CD 파이프라인에 typedoc + docusaurus build를 연결하면 배포 자동화도 가능합니다.