Docs site 생성시 추천할 프레임워크/라이브러리 추천

 

1) Astro + Starlight (메인 문서 사이트)

  • 강점: 문서 사이트로서 기본 UX가 좋고, i18n을 공식 가이드로 제공(다국어 라우팅/폴백/RTL 등)하며 [2], “문서 전용 기능(검색/SEO/코드 하이라이팅/다크모드 등)”을 전면으로 지원합니다. [3]
  • API 50% 대응: 순수 API 자동화는 Sphinx/MkDocs보다 “내장 표준”이 약하므로, 아래 2) 또는 3) 방식으로 API 페이지를 생성/임포트하는 전략을 같이 잡는 게 좋습니다.
  • Cloudflare: 정적 사이트 배포 흐름과 궁합이 매우 좋습니다(Cloudflare Pages에 올리기 쉬운 구조).

2) Starlight + Typedoc(또는 언어별 doc generator)로 API HTML/Markdown 생성

  • TS/JS라면 Typedoc, Python이면 pdoc/Griffe 기반 등으로 API 레퍼런스 페이지를 자동 생성하고 Starlight 사이트에 “레퍼런스 섹션”으로 편입하는 방식.
  • 장점: 예제/가이드는 Starlight에서 최고의 UX로 쓰고, API는 자동화로 정확성을 확보.

3) Sphinx + PyData Sphinx Theme (API가 파이썬 중심이고 참조 구조가 복잡한 경우)

  • 강점: API 자동화(autodoc), cross-reference, 인덱스/도메인 기능 등 “레퍼런스 50%”를 가장 안정적으로 처리.
  • 다국어: 가능은 하지만(번역 워크플로) 운영 복잡도가 올라갈 수 있어, “문서 UX” 관점에서는 Starlight가 더 편한 경우가 많습니다.
  • 결론: API가 파이썬이고 레퍼런스 품질이 최우선이면 Sphinx, 그렇지 않으면 Starlight 중심이 더 깔끔합니다.

차선/상황별 유력 옵션 (나머지 7개)

4) MkDocs + Material + mkdocstrings

  • Markdown 중심 작성이 쉽고, API 문서(특히 Python) 자동화 경험이 좋습니다.
  • “가이드/예제”도 잘 만들 수 있어, Starlight 대신 MkDocs로 일원화하려면 좋은 선택.

5) Docusaurus

  • 다국어/버전 문서 운영을 강하게 가져가야 하거나, React 기반 커스텀이 필요하면 유리.
  • 다만 “문서 전용 간결함”은 Starlight/MkDocs 쪽이 더 가볍게 느껴질 수 있습니다.

6) Starlight + OpenAPI(스키마 기반) 레퍼런스

  • 당신의 API가 REST/HTTP(OpenAPI) 기반라면, OpenAPI 스펙으로 레퍼런스를 생성(별도 생성기 사용)하고 Starlight에 넣는 방식이 유지보수에 강합니다.
  • “API 50%”가 HTTP API라면 이 루트가 특히 좋습니다(언어에 종속되지 않음).

7) Starlight + Jupyter/노트북 예제(정적 변환)

  • 예제 50%를 “실행 가능한 튜토리얼”로 보여주고 싶으면, 노트북을 정적 페이지로 변환해 문서에 포함시키는 패턴이 잘 맞습니다.
  • (구체 도구는 사용하는 언어/형식에 따라 달라서, 다음 질문에서 확정하는 게 좋습니다.)

8) Sphinx + MyST (Markdown 기반 Sphinx)

  • Sphinx의 강력한 레퍼런스 자동화는 유지하면서, 작성은 Markdown 중심으로 하고 싶다면 고려할 만합니다.
  • 다만 i18n/버전/UX를 “Starlight 급”으로 맞추려면 테마/구성에 손이 갈 수 있습니다.

9) 두 사이트 분리 운영(가이드/예제는 Starlight, API는 Sphinx/MkDocs)

  • 가장 흔한 “타협안”입니다.
  • 장점: 각 도구의 장점을 극대화.
  • 단점: 검색/내비게이션/스타일 통일과 배포 파이프라인이 2개가 되어 관리 포인트가 늘어납니다.

10) 버전 미정 대비: ‘버전 전략을 나중에 끼울 수 있는’ 구조로 설계

  • 지금 버전이 미정이면, 처음부터 “버전 디렉터리 전략(v1/, v2/)” 또는 “브랜치/태그 기반 빌드”를 염두에 둔 IA(정보구조)로 시작하는 게 안전합니다.
  • Starlight든 Docusaurus든, 초기에 URL 전략만 잘 잡으면 나중에 덜 아픕니다.

 추천 결론(실행 플랜)

당장 현실적으로는 아래 2가지 중 하나가 가장 깔끔합니다.

플랜 A (가장 추천): Starlight를 메인으로 + API는 생성해서 끼우기

  • 가이드/예제: Starlight에서 한/영 i18n 구조로 작성 (Starlight i18n 가이드가 있음 [2])
  • API 레퍼런스: 언어/스펙에 맞는 도구로 자동 생성 → 결과물을 Starlight에 포함
  • 배포: Cloudflare Pages로 단일 정적 사이트 배포

플랜 B: MkDocs Material로 일원화

  • 한/영 + API 자동화 + 가이드/예제 모두를 MkDocs 중심으로 처리(특히 Python이면 강함)
  • 프론트 UX는 Starlight만큼 “제품급”을 내기엔 제한이 있을 수 있지만, 운영은 단순해질 수 있음

참고문헌

댓글

댓글 쓰기