마이그레이션 개요

이 문서에서는 기존 도큐사우루스 1 사이트를 운영하고 있는 경우 도큐사우루스 2로 마이그레이션하는 방법을 안내합니다.

가능한 쉽게 마이그레이션할 수 있도록 마이그레이션 CLI를 제공합니다.

주요 차이점

도큐사우루스 1은 리액트를 서버 측 템플릿 엔진처럼 사용해서 문서 사이트 생성을 위한 기능만 제공했습니다. 때문에 웹 브라우저에서 리액트를 로딩하지는 않았습니다.

도큐사우루스 2는 웹 브라우저에서 사용할 수 있는 리액트의 모든 기능을 활용해 단일 페이지 애플리케이션을 위한 도구로 완전히 새롭게 만들었습니다. 그래서 더 다양한 활용을 할 수 있습니다. 하지만 도큐사우루스 1에서의 장점들, 예를 들면 간단한 시작, 버전 관리, i18n 등의 기능은 그대로 유지합니다.

한발 더 나아가 도큐사우루스 2는 강력한 정적 사이트 생성 기능을 지원합니다. 이를 통해 다양한 콘텐츠 기반의 웹사이트(문서, 블로그, 랜딩 사이트, 마케팅 페이지 등)를 매우 빠르게 구현할 수 있습니다.

그렇지만 여전히 주요 관심은 문서를 잘 만들고 보여주는것에 있습니다. 도큐사우루스 2는 리액트 애플리케이션으로 구현했기 때문에 다양한 형식의 웹사이트를 지원할 수 있을 뿐입니다. 이제 도큐사우루스는 문서 뿐 아니라 다양한 웹사이트를 만들 수 있습니다.

도큐사우루스 1 구조

여러분의 도큐사우루스 1 사이트는 아마도 아래와 비슷한 구조일겁니다.

├── docs
└── website
    ├── blog
    ├── core
    │   └── Footer.js
    ├── package.json
    ├── pages
    ├── sidebars.json
    ├── siteConfig.js
    └── static

도큐사우루스 2 구조

마이그레이션 작업 후 여러분의 도큐사우루스 2 사이트는 아래와 같은 구조로 만들어집니다.

├── docs
└── website
    ├── blog
    ├── src
    │   ├── components
    │   ├── css
    │   └── pages
    ├── static
    ├── package.json
    ├── sidebars.json
    ├── docusaurus.config.js

정보

마이그레이션 작업 시에는 /docs 디렉터리의 위치를 변경하지는 않습니다. 하지만 도큐사우루스 v2 사이트는 일반적으로 /website 디렉터리 안에 /docs 디렉터리가 위치합니다.

v2 마이그레이션 이후에 /docs 디렉터리의 위치는 원하는 곳으로 자유롭게 변경할 수 있습니다.

마이그레이션 절차

온전하게 동작하는 도큐사우루스 2 웹 사이트로 이전하려면 아래와 같은 항목을 고려해서 처리해주어야 합니다.

• 패키지
• CLI 명령어
• 사이트 설정
• 마크다운 파일
• 사이드바 파일
• 페이지, 컴포넌트, CSS
• 버전 지정된 문서
• i18n 지원 🚧

자동으로 처리되는 마이그레이션 절차

마이그레이션 CLI가 마이그레이션에 필요한 많은 것들을 처리해줍니다.

하지만 일부 항목은 자동으로 처리하지 못하며 여러분이 직접 수동으로 처리해주어야 합니다.

노트

마이그레이션 CLI를 실행하고 누락되는 부분만 수동 마이그레이션 절차에 따라 처리하는 것을 권장합니다.

수동으로 처리하는 마이그레이션 절차

일부 항목의 마이그레이션은 자동으로 처리되지 못합니다(특히 페이지 같은 경우). 이런 항목은 수동으로 처리할 수 있습니다.

수동 마이그레이션 가이드에서 필요한 절차를 확인할 수 있습니다.

지원

궁금한 점은 #migration-v1-to-v2 디스코드 채널에 질문을 남겨주세요.

도움이 필요하다면 마이그레이션 관련 풀 리퀘스트 요청 시 @slorber를 태그로 추가해주세요.

여러분이 v1 사이트를 마이그레이션하는 것을 도와줄 자원봉사자를 연결해줄 수도 있습니다.

마이그레이션 풀 리퀘스트 예

Create React App이나 Flux에서 도큐사우루스 v1 사이트를 마이그레이션하기 위한 풀 리퀘스트 요청을 어떻게 처리했는지 참고하세요.