문서 사이트 기술 선정

이 페이지는 2026-10-12에 주요 정적 문서 프레임워크에 대해 수행한 조사 결론과, 이 리포지터리 문서 사이트 프레임워크의 최종 결정을 기록합니다.

결정 기록

날짜	결정	이유
2026-10-12(조사일)	Astro Starlight를 채택, VitePress에서 마이그레이션	Starlight는 기본적으로 클라이언트 JS가 0이고 프레임워크 독립적이어서 이 리포지터리의 “런타임 JS 0” 철학에 가장 잘 맞음. 세 개의 데이터 기반 참조 페이지를 순수 Astro 컴포넌트로 옮겨 vue / vitepress / vite 의존성 세 개를 완전히 제거. Node ≥22.12 요구 사항은 감수 가능
2026-10-12(조사일, 사전 판단)	VitePress 유지	당시에는 마이그레이션 수익이 비용을 덮지 못했음 — 가족 7개 사이트가 모두 VitePress 위에 있고, 이 리포지터리의 문서 사이트도 이미 완전히 구축되어 있었음. 이 결론은 같은 날의 마이그레이션 결정으로 대체되었으며, 아래에 역사 기록으로 보존

마이그레이션 자체는 한 번에 완료되었습니다(단일 커밋 안에 Astro 골격을 구축하고 모든 페이지를 옮겨, 중간 상태에서 빌드가 불가능한 일이 없도록 함). 가족의 나머지 사이트는 여전히 VitePress를 사용하며, 이 리포지터리는 가족 차원의 통일을 요구하지 않습니다. 향후 가족 차원에서 프레임워크를 통일하게 되면, 이 리포지터리의 Starlight 실천이 그대로 참고가 됩니다.

조사 결론(역사 기록, 2026-10-12 데이터 기반)

오늘 처음부터 시작하고, 가족 일관성 제약이 없었다면 가장 강력한 대안은 Astro Starlight입니다 — 성능, 프레임워크 독립성, 기본 클라이언트 JS 0으로 이 리포지터리의 “런타임 JS 0” 철학에 가장 잘 맞습니다. (이 판단이 결국 위의 마이그레이션 결정으로 이어졌습니다.)
VuePress는 사실상 정체되었으며, 어떤 새 프로젝트에서도 채택을 권장하지 않습니다(리포지터리의 최근 푸시가 2024-08-07에 머물러 있고, v2는 여전히 rc 상태).
마이그레이션 전 장기적으로 관찰할 가치가 있었던 유일한 것은 VitePress 2.0입니다(당시 next 태그는 2.0.0-alpha.20, alpha 단계).

활동 데이터

데이터 수집일: 2026-10-12. GitHub 데이터는 api.github.com에서, npm 다운로드 수는 2026-10-04 ~ 10-10 주간 통계, 버전 번호는 registry.npmjs.org dist-tags에서 가져왔습니다. star 수는 시간이 지나면 변하므로, 인용할 때 신선도에 주의하세요.

프레임워크	기술 스택	GitHub Stars	리포지터리 최근 푸시	npm 주간 다운로드	최신 안정 버전
VitePress	Vue 3 + Vite	18.4k	2026-10-11	1,305,159	1.6.4(next: 2.0.0-alpha.20)
Docusaurus	React + MDX	66.5k	2026-10-10	1,504,459	3.10.2
Astro Starlight	Astro(프레임워크 독립)	9.4k	2026-10-09	1,431,284(astro 본체 7.22M)	astro 7.3.8 / starlight 0.42.6
docsify	런타임 JS 렌더링	31.5k	2026-10-11	80,727	5.0.0
Nextra	Next.js + React	13.9k	2026-07-31	238,757	4.6.1
Fumadocs	Next.js + React	13.3k	2026-10-09	—	—
MkDocs Material	Python	27.6k	2026-10-02	PyPI, 해당 없음	—
Sphinx	Python / RST	8.1k	2026-10-05	PyPI, 해당 없음	—
VuePress	Vue + Webpack	22.7k	⚠️ 2024-08-07	71,177	1.9.10(v2는 2.0.0-rc.31에 머무름)
Dumi	Umi + React	3.8k	2026-09-14	20,163	2.4.50
Rspress	Rspack + React	2.3k	2026-10-10	19,631	1.47.2(2.0 beta.21)

핵심 수치: VitePress와 Docusaurus는 월 다운로드 100만을 넘기는 단 두 개의 선두 주자입니다. Starlight는 Astro 본체(722만)에 힘입어 떠오른 제3의 축입니다. VuePress는 2.3만 star를 보유하고 있으나 리포지터리가 2년 넘게 커밋이 없으며, 사실상 VitePress로 대체되었습니다.

티어별 장단점

1티어: VitePress / Docusaurus / Astro Starlight

VitePress(이 리포지터리가 마이그레이션 전에 사용 중; 가족 나머지 사이트는 여전히 사용 중)

장점: Vue 단일 파일 컴포넌트를 markdown에 직접 쓸 수 있음(이 리포지터리의 토큰 레퍼런스 / 컴포넌트 계약 / 골든 케이스 세 참조 페이지가 바로 이것으로 구현됨). 빌드 시 데이터 로더(*.data.ts)가 JSON 원본을 읽기에 자연스럽게 맞고, dev 시 watch glob을 설정하면 핫 갱신도 됨. Vite dev가 매우 빠름. 기본 테마를 그대로 쓸 수 있어 설정이 거의 필요 없음. 중국어 커뮤니티와 자료가 풍부함.
단점: MDX 지원이 약함(MDX 생태계가 아님). 버전 관리 문서, i18n 등 기업급 기능은 직접 구축하거나 플러그인을 찾아야 함. 테마 커스터마이징 깊이는 Docusaurus에 못 미침. 검색이 로컬 인덱스라 대형 사이트에서는 성능이 보통임.

Docusaurus(Meta 제작, 생태계가 가장 큼)

장점: 버전 관리 문서 플러그인(여러 버전 문서 공존)과 i18n이 모든 프레임워크 중 가장 성숙함. MDX 생태계, 플러그인 체계, 테마 주입(swizzle)이 잘 갖춰져 있음. Meta가 뒤를 받쳐 장기 유지 보수에 보장이 있음.
단점: React 일가 의존성이 무겁고, 빌드 산출물 JS 크기가 큼. 설정 항목이 많고 인지 부담이 큼. 데이터 파이프라인(loadContent 라이프사이클)을 JSON 원본에 연결하는 것은 VitePress의 로더보다 더 우회함. 가족에 선례가 없음.

Astro Starlight(프레임워크 독립적, 성능 벤치마크; 이 리포지터리가 현재 사용 중)

장점: 기본 클라이언트 JS 0으로, 이 리포지터리의 “런타임 JS 0” 철학에 가장 잘 맞음. 콘텐츠 컬렉션(Content Collections)이 타입 안전한 데이터 계층을 제공. Vue / React / Svelte 컴포넌트를 섞어 쓸 수 있음. 빌드 산출물이 가장 가벼움. Starlight 테마의 문서 경험이 뛰어남(사이드바, 앵커 내비게이션, i18n 내장).
단점: Starlight는 여전히 0.x(0.42.6)이며, API에 breaking change가 있을 수 있음. 콘텐츠 컬렉션이 파일형 콘텐츠(md / mdx)를 대상으로 하므로, tokens/*.json 같은 외부 JSON을 읽으려면 컬렉션을 우회해 .astro 페이지에서 직접 가져와야 함(이 리포지터리는 frontmatter에서 codegen 모듈을 직접 호출하는 방식으로 해결). 가족에 선례가 없어 배포 / nginx / 사이드바 관례를 따로 밟아야 했음(이 리포지터리가 이미 밟음, 배포 안내 참고).

2티어: Nextra / Rspress / Fumadocs / Dumi

Nextra: Next.js 생태계, MDX이 강함, 문서가 아름답지만 Next.js + React에 강하게 결합됨. 배포 모델(SSG / SSR / Edge)이 가족의 nginx 정적 호스팅과 다르고, v4의 콘텐츠 디렉터리 관례가 VitePress와 크게 다름. 마이그레이션 동기가 없음.
Rspress(바이트 web-infra-dev 제작): 빌드 속도가 가장 빠름(Rspack). 수천 페이지 규모의 대형 문서 사이트에서는 VitePress보다 확실히 우위. 중국어 유지 보수자 커뮤니티가 친절함. 단, 생태계 / 플러그인이 가장 적고(주간 다운로드 2만), 데이터 로더에 표준 패러다임이 없음 — 이 리포지터리는 30페이지 남짓이라 속도를 위해 학습 비용을 지불할 일이 없음.
Fumadocs: 지난 2년간 성장세가 가장 가파른 신예(13.3k star, 열려 있는 issue가 2개뿐). Next.js + 현대적 디자인 시스템, 검색 / 뷰 전환 경험이 좋음. 마찬가지로 Next.js에 강하게 결합되어 있고, 국내 문서 자료가 적음. 저장해 두면 좋으나 지금 도입은 권장하지 않음.
Dumi: 컴포넌트 라이브러리 데모(live demo, 속성 표 자동 생성)를 위해 만들어짐. 이 리포지터리는 빌드 시 토큰 리포지터리이며 데모로 보여줄 런타임 UI가 전혀 없어서 핵심 강점을 전혀 쓸 수 없고, Umi / React에 강하게 결합됨. 명확히 제외.

3티어와 특수 항목

MkDocs Material / Sphinx(Python 계열): 문서 품질은 매우 높으나 Python 도구 체인이 필요해 이 리포지터리의 Node ≥20 + pnpm + TS 도구 체인과 다른 생태계에 있으며, codegen의 TS 타입과 적재 함수를 재사용할 수 없음. 제외.
docsify(런타임 렌더링): 빌드 시가 없고 CDN에서 가져다 쓰면 되어 “단일 페이지로 빠르게 오픈”하는 작은 문서에 적합. 단, 빌드 시에 HTML을 생성하지 않고(SEO가 약하고 첫 화면이 느림), 빌드 시 데이터 로더로 schema 검증을 할 수도 없음(이 리포지터리의 참조 페이지가 바로 이 능력에 의존함). 제외.

이 리포지터리 제약과의 항목별 대조

이 리포지터리의 제약 / 요구	VitePress	Docusaurus	Starlight	기타
가족 7개 사이트 동일 체계(nginx 접두사 / 사이드바 / 배포)	✅ 가족 나머지 사이트가 사용 중	❌ 다시 밟아야 함	✅ 이 리포지터리가 이미 밟음(nginx 세 가지 계약은 계속 유효, 배포 안내 참고)	❌
빌드 시 JSON 원본을 읽어 참조 페이지 렌더링	✅ 네이티브 로더, 이미 구현됨	⚠️ 커스텀 플러그인 필요	✅ 이미 구현됨(`.astro` 페이지 frontmatter에서 codegen의 load / resolve를 직접 호출)	⚠️ 더 번거로움
단일 중국어, i18n 요구 없음	✅	장점을 쓸 수 없음	✅	—
상호작용 데모 없는 prose + 표 + 코드	✅	✅	✅	✅
“런타임 JS 0” 기질	⚠️ 런타임 JS 있음(사이트에만, 레드라인 범위 밖)	❌ JS가 무거움	✅ 기본 JS 0	—
codegen TS 모듈 재사용(타입 / 검증)	✅ 검증됨(vite ^5.4.21부터 SSR이 `import.meta.dirname` 지원)	✅	✅ 검증됨(astro 7에 vite 8이 내장되어 SSR이 `import.meta.dirname` 지원)	✅

두 가지 판단 근거를 보충합니다:

“런타임 JS 0” 레드라인이 다루는 것은 codegen의 dist/ 산출물이지 문서 사이트가 아닙니다. 문서 사이트 자체가 프레임워크 런타임을 구동하더라도 어떤 레드라인도 위반하지 않습니다 — dist/와 완전히 격리되어 있고, 빌드 산출물은 .gitignore에 들어갑니다. 단, Starlight로 마이그레이션한 뒤에는 사이트 자체도 기본 클라이언트 JS 0이 되어(검색 / 테마 전환 등 소수의 상호작용만 필요에 따라 로드), 레드라인의 정신에 더 가까워졌습니다.
Docusaurus의 버전 관리 문서와 i18n 장점은 이 리포지터리에서 쓸 수 없습니다: 이 리포지터리는 단일 중국어, 단일 버전이며 콘텐츠가 codegen을 따라가서 “구버전 토큰 문서의 공존”이라는 상황이 없습니다.

후속 관찰 항목

Starlight 1.0: 이 리포지터리는 현재 ^0.42.6으로 고정. 0.x 단계에서는 여전히 breaking change가 있을 수 있으며, 1.0 정식 출시 뒤 업그레이드 경로를 평가(Starlight의 마이그레이션 가이드가 변경점을 명시).
VitePress 2.0: beta에 진입한 뒤 평가. 가족 나머지 사이트는 여전히 VitePress 위에 있으며, 주요 관전 포인트는 빌드 성능과 Vite 7 후속 지원.
재선정을 유발하는 신호: Starlight가 장기적으로 유지 보수되지 않거나, 가족 차원에서 문서 프레임워크 통일을 결정할 때(그때는 이 리포지터리의 Starlight 실천이 그대로 참고가 됨).