Docusaurus를 Astro Starlight로 마이그레이션

Docusaurus는 React 문서 에코시스템에 잘 기여해왔습니다. 팀은 버전 관리, 검색, MDX 지원을 갖춘 문서 사이트를 빠르게 구축할 수 있었습니다. 하지만 모든 방문자에게 전체 React 런타임을 배송하며, 그 무게는 모든 Lighthouse 감사에서 드러납니다.

Astro Starlight는 문서를 위해 특별히 구축되었습니다. 기본적으로 정적 HTML을 렌더링하고, 명시적으로 옵트인하지 않는 한 JavaScript를 배송하지 않으며, 기본 제공 검색, 사이드바 네비게이션, i18n을 포함합니다. MDX 파일은 직접 전환됩니다. Astro 팀은 마이그레이션 경로를 잘 문서화하고 있습니다.

Docusaurus 사이트가 모바일에서 느리다면, 문서가 증가하면서 빌드 시간이 계속 늘어난다면, 또는 정적 콘텐츠에서 React 하이드레이션 문제와 싸우는 것에 지쳤다면 — Starlight가 모든 것을 해결합니다.

규모에서의 Docusaurus의 실제 문제

클라이언트 측 JavaScript 오버헤드

Docusaurus는 브라우저에 React를 배송합니다. 모든 페이지 로드에는 React 런타임, React DOM, 클라이언트 측 라우팅 레이어가 포함됩니다. 페이지의 99%가 정적 텍스트와 코드 블록인 문서 사이트의 경우 이는 불필요한 가중치입니다. 모바일 Lighthouse 점수는 일반적으로 45-65 사이에 위치합니다.

빌드 성능 저하

문서 컬렉션이 몇 백 페이지를 넘으면서 Docusaurus 빌드 속도가 눈에 띄게 느려집니다. Webpack 번들링이 상황을 악화시킵니다. 500개 이상의 문서 페이지를 가진 팀은 5분을 초과하는 빌드 시간을 보고하며, 이는 CI/CD 피드백 루프를 방해합니다.

플러그인 에코시스템 종속성

Docusaurus 플러그인은 내부 아키텍처에 밀접하게 결합되어 있습니다. 사용자 정의 remark 플러그인이 필요하신가요? 작동하지만 구성 계층이 복잡성을 추가합니다. 검색 제공자를 바꾸고 싶으신가요? Docusaurus의 사전 설정 시스템 내에서 작업하고 있으며, 이는 가능한 것을 제한합니다.

사이드바 구성 경직성

Docusaurus 사이드바 구성은 category, items, type 필드가 있는 특정 JSON/JS 스키마를 사용합니다. 작동하지만 깊은 중첩이 있는 큰 문서 트리의 경우 구성이 복잡해집니다. 섹션을 재정렬하려면 파일을 이동하는 대신 구성 파일을 편집해야 합니다.

React 컴포넌트 종속성

Docusaurus의 사용자 정의 컴포넌트는 클라이언트에서 하이드레이션되는 React 컴포넌트입니다. 대화형 예제, 탭 콘텐츠, 또는 사용자 정의 주석을 구축한 경우, 상호 작용이 최소한일 때도 모두 React 하이드레이션 비용을 발생시킵니다.

Astro Starlight가 제공하는 것

기본적으로 0 JavaScript

Starlight는 순수 정적 HTML과 CSS를 생성합니다. 명시적으로 대화형 아일랜드를 추가하지 않는 한 프레임워크 런타임이 브라우저에 배송되지 않습니다. 문서 페이지는 3G 연결에서 200ms 이내로 로드됩니다. Lighthouse 점수는 일관되게 95-100에 도달합니다.

MDX 호환성

Starlight는 기본적으로 Astro의 MDX 통합을 포함합니다. 기존 .mdx 파일이 즉시 작동합니다. Frontmatter 필드가 깔끔하게 매핑됩니다 — title, description, sidebar_label 모두 Starlight 동등물이 있습니다. Remark 및 rehype 플러그인은 변경 없이 이월됩니다.

기본 제공 Pagefind 검색

Starlight는 빌드된 HTML을 인덱싱하고 완전히 브라우저에서 실행되는 정적 검색 엔진인 Pagefind와 함께 제공됩니다. 외부 서비스 없음, API 키 없음, Algolia 크롤 지연 없음. 검색은 오프라인에서 작동하며 번들에 약 10KB를 추가합니다. Algolia가 특별히 필요한 팀의 경우 공식 Starlight DocSearch 플러그인이 있습니다.

파일 기반 사이드바 생성

Starlight는 파일 구조에서 사이드바를 자동 생성할 수 있습니다. MDX 파일을 폴더에 놓으면 사이드바에 나타납니다. 명시적 구성으로 여전히 재정의할 수 있지만 기본 동작은 대부분의 사이드바 구성 유지보수를 제거합니다.

유형 안전이 있는 콘텐츠 컬렉션

Starlight는 Astro의 콘텐츠 컬렉션을 사용하며, 이는 빌드 시간에 Zod 스키마에 대해 frontmatter를 검증합니다. Frontmatter 필드의 오타는 배포 전에 포착되고 사용자가 발견하지 않습니다.

마이그레이션 프로세스

단계 1: 감사 및 계획

페이지 수, 사용자 정의 컴포넌트, 플러그인 사용, 사이드바 구조, 버전 관리 설정, 사용자 정의 테마 등 Docusaurus 사이트를 인벤토리하는 것으로 시작합니다. 모든 Docusaurus 기능을 Starlight 동등물로 매핑하고 사용자 정의 솔루션이 필요한 간격을 표시합니다.

단계 2: Starlight 스캐폴딩

yarn create astro --template starlight를 사용하여 새 Starlight 프로젝트를 시작하고 기존 사이트의 구조와 일치하도록 구성합니다. 콘텐츠 컬렉션을 설정하고, astro.config.mjs를 구성하며, 현재 URL 구조를 반영하는 폴더 계층을 설정합니다.

단계 3: 콘텐츠 마이그레이션

MDX 파일은 최소한의 변경으로 전환됩니다. 우리는 다음을 처리합니다:

• Frontmatter 재매핑: Docusaurus 특정 필드 sidebar_position, sidebar_label, slug이 Starlight의 frontmatter 스키마로 변환됩니다
• import 문 업데이트: 컴포넌트 import가 Docusaurus 경로에서 Astro 컴포넌트 경로로 변경됩니다
• 주석 구문: Docusaurus는 :::note 구문을 사용하고 Starlight는 <Aside> 컴포넌트 또는 자체 주석 구문을 사용합니다
• 탭 컴포넌트: Docusaurus의 <Tabs>과 <TabItem>이 Starlight의 기본 제공 탭 컴포넌트로 교체됩니다

단계 4: 사이드바 구성 재매핑

category/items 패턴을 사용하는 Docusaurus 사이드바 구성이 Starlight의 사이드바 구성 형식으로 변환됩니다. 가능한 경우 파일 구조로 구동되는 자동 생성 사이드바로 전환하여 구성 유지보수를 0으로 줄입니다.

// Docusaurus sidebars.js
module.exports = {
  docs: [
    { type: 'category', label: 'Getting Started', items: ['intro', 'installation'] },
  ],
};

// Starlight astro.config.mjs
starlight({
  sidebar: [
    { label: 'Getting Started', autogenerate: { directory: 'getting-started' } },
  ],
})

단계 5: 플러그인 및 통합 매핑

Docusaurus 플러그인을 Astro 통합으로 교체합니다:

• @docusaurus/plugin-google-gtag → Astro의 @astrojs/partytown (인라인 gtag 포함)
• @docusaurus/plugin-sitemap → @astrojs/sitemap
• Algolia DocSearch → Pagefind (기본 제공) 또는 starlight-docsearch 플러그인
• @docusaurus/plugin-client-redirects → 구성의 Astro 리다이렉트 또는 astro-redirect
• 사용자 정의 remark/rehype 플러그인 → 직접 이월, 동일한 플러그인 에코시스템

단계 6: 검색 마이그레이션

Algolia DocSearch를 사용하는 경우 기본적으로 Pagefind로 마이그레이션합니다. Pagefind는 빌드 시간에 인덱싱하고, 외부 서비스가 필요 없으며, 퍼지 매칭으로 즉시 검색을 제공합니다. 팀이 특별히 Algolia가 필요한 경우 — 분석 또는 AI 기반 답변을 위해 — 공식 starlight-algolia 플러그인을 구성합니다.

단계 7: QA 및 출시

이전 및 새 사이트 간의 전체 크롤 비교를 실행하고, 모든 URL이 확인되는지 검증하고, 검색 기능을 테스트하고, 모바일 렌더링을 검증하고, Lighthouse 점수가 목표를 충족하는지 확인합니다.

SEO 보존 전략

문서 사이트는 상당한 검색 권위를 축적합니다. 모든 것을 보호합니다:

• URL 동등성: 기존 URL 구조와 정확히 일치합니다. Docusaurus가 /docs/getting-started를 제공한 경우 Starlight도 동일한 경로를 제공합니다
• 301 리다이렉트: 변경되어야 하는 URL의 경우 Vercel 또는 Cloudflare에서 서버 레벨 리다이렉트를 구성합니다
• Canonical 태그: 모든 페이지는 적절한 canonical URL을 받습니다
• Sitemap 생성: @astrojs/sitemap은 Search Console에 제출된 업데이트된 sitemap을 생성합니다
• 메타 보존: 제목 태그, 메타 설명, Open Graph 태그는 기존 frontmatter에서 이월됩니다
• 구조화된 데이터: 해당하는 경우 문서 특정 JSON-LD를 추가합니다

타임라인 및 가격

Docusaurus에서 Starlight로의 대부분의 마이그레이션은 사이트 복잡성에 따라 1-3주에 완료됩니다:

• 소규모 사이트 (50페이지 미만, 최소 사용자 정의 컴포넌트): 1주, $3,000부터 시작
• 중간 규모 사이트 (50-200페이지, 사용자 정의 컴포넌트, 버전 관리): 2주, $6,000부터 시작
• 대규모 사이트 (200페이지 이상, 높은 사용자 정의, 다중 로케일): 3주 이상, $10,000부터 시작

모든 프로젝트는 특정 Docusaurus 설정을 평가하고 정확한 범위 및 타임라인을 제공하는 무료 마이그레이션 감사로 시작됩니다.