GitBook에서 마이그레이션

GitBook은 버전 제어 통합 및 사용자 정의 가능한 기능을 통해 공동 작업 방식으로 문서와 책을 작성하고 게시하기 위한 웹 기반 플랫폼입니다.

GitBook과 Astro의 주요 유사점

GitBook과 Astro는 프로젝트 마이그레이션에 도움이 되는 몇 가지 유사점을 공유합니다.

Astro와 GitBook 모두 Markdown을 지원합니다. GitBook의 Git Sync 기능을 활용하여 기존 문서를 모두 마이그레이션할 수 있습니다.
Astro와 GitBook은 모두 파일 기반 라우팅 형식을 사용합니다. 기존 콘텐츠에 Astro의 파일 구조를 사용하고 새 페이지를 추가하는 것이 친숙하게 느껴질 것입니다.

GitBook 문서를 Astro로 마이그레이션하면 몇 가지 중요한 차이점을 발견할 수 있습니다.

GitBook 사이트는 온라인 대시보드를 사용하여 편집됩니다. Astro에서는 코드 편집기 및 개발 환경을 사용하여 사이트를 유지 관리합니다. 컴퓨터에서 로컬로 개발하거나 StackBlitz, CodeSandbox 또는 Gitpod와 같은 클라우드 편집기/개발 환경을 선택할 수 있습니다.
GitBook은 콘텐츠를 데이터베이스에 저장합니다. Astro에서는 각 페이지의 콘텐츠에 대한 프로젝트 디렉터리에 개별 파일 (일반적으로 Markdown 또는 MDX)이 있습니다. 또는 콘텐츠용 CMS와 Astro를 사용하여 데이터를 가져와 표시할 수도 있습니다.
GitBook은 콘텐츠를 위한 Markdown 위에 사용자 정의 구문을 사용합니다. Astro는 GitBook에서 사용하는 것과 유사한 구문을 제공하는 선택적 Markdoc 통합을 통해 Markdoc을 지원합니다.

GitBook 문서 사이트를 Astro로 변환하려면 공식 Starlight 문서 테마 시작 템플릿으로 시작하거나 테마 쇼케이스에서 더 많은 커뮤니티 문서 테마를 탐색하세요.

공식 스타터 중 하나를 사용하여 새로운 Astro 프로젝트를 시작하려면 --template 인수를 create astro 명령에 전달할 수 있습니다. 또는 GitHub의 기존 Astro 저장소에서 새 프로젝트를 시작할 수 있습니다.

npm create astro@latest -- --template starlight

pnpm create astro@latest --template starlight

yarn create astro --template starlight

새로운 Astro 프로젝트가 생기면 기존 GitBook 콘텐츠를 새로운 Astro 프로젝트에 동기화할 수 있습니다. GitBook에는 GitBook 콘텐츠를 GitHub/GitLab 저장소에 자동으로 동기화하는 Git Sync 기능이 있습니다.

문서 템플릿의 콘텐츠 컬렉션에 직접 동기화하려면 src/content/docs/en 또는 src/content/docs를 프로젝트 디렉터리로 지정하세요.

콘텐츠를 동기화하면 이제 Astro 저장소에 GitBook 콘텐츠 사본이 생성됩니다. 향후 GitBook과의 동기화를 방지하려면 git sync를 비활성화하세요.

이제 콘텐츠를 Astro 프로젝트로 마이그레이션했지만 즉시 사용할 수는 없습니다. Astro 사이트에서 이 콘텐츠를 사용하려면 GitBook의 구문을 Astro와 호환되는 형식으로 수동으로 변경하는 데 시간이 필요합니다.

Astro의 Markdoc 통합에서는 파일 확장자가 .mdoc여야 합니다. 이는 .mdx 및 .md와 같은 다른 Markdown 확장과의 충돌을 피하기 위한 것입니다.
GitBook 구문은 GitBook 파일에서 닫는 태그를 나타내는 / 접두사가 end로 대체되는 Markdoc과 다릅니다. 파일 전체에서 이 표기법을 업데이트해야 합니다.
GitBook의 일부 기능은 사용자 정의 컴포넌트에 의존합니다. 이러한 컴포넌트는 Astro에 존재하지 않으며 Markdoc의 구성 tags 속성을 통해 생성 및 프로젝트에 추가되거나 파일에서 제거되어야 합니다.