수동으로 마이그레이션 처리

이 수동 마이그레이션 과정은 자동 마이그레이션 과정 이후에 수행하여 누락된 부분을 완성하거나 마이그레이션 CLI 출력의 문제를 디버깅하는 데 사용해야 합니다.

프로젝트 설정

package.json

스코프 패키지명

도큐사우루스 2에서는 스코프 패키지명을 사용합니다.

• docusaurus → @docusaurus/core

이를 통해 공식적으로 도큐사우루스에서 제공하는 패키지와 커뮤니티에서 만든 패키지를 구별할 수 있습니다. 다시 말해 도큐사우루스의 모든 공식 패키지는 @docusaurus/ 네임스페이스에 속합니다.

한편 도큐사우루스 1이 제공하던 기본 문서 사이트 기능은 이제 @docusaurus/preset-classic에서 제공합니다. 때문에 이에 대한 종속성이 추가되어야 합니다.

package.json

{
  dependencies: {
-   "docusaurus": "^1.x.x",
+   "@docusaurus/core": "^2.0.0-beta.0",
+   "@docusaurus/preset-classic": "^2.0.0-beta.0",
  }
}

팁

최신 도큐사우루스 2 버전을 사용하세요. 여기에서 latest 태그로 확인할 수 있습니다.

CLI 명령어

CLI 명령도 docusaurus-command 대신 docusaurus \<command> 형식으로 이름이 변경되었습니다.

package.json의 "scripts" 섹션을 다음과 같이 업데이트해야 합니다:

package.json

{
  "scripts": {
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy"
    // ...
  }
}

일반적인 도큐사우루스 2의 package.json은 다음과 같습니다:

package.json

{
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "serve": "docusaurus serve",
    "clear": "docusaurus clear"
  },
  "dependencies": {
    "@docusaurus/core": "^2.0.0-beta.0",
    "@docusaurus/preset-classic": "^2.0.0-beta.0",
    "clsx": "^1.1.1",
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  },
  "browserslist": {
    "production": [">0.5%", "not dead", "not op_mini all"],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

build 디렉터리 참조 업데이트하기

도큐사우루스 1에서는 모든 빌드 결과물이 website/build/\<PROJECT_NAME>에 있습니다.

도큐사우루스 2에서는 website/build로 위치가 변경되었습니다. 올바른 build 디렉터리에서 생성된 파일을 읽도록 배포 설정을 업데이트하세요.

GitHub Pages에 배포한다면 yarn publish-gh-pages 스크립트 대신 yarn deploy를 실행하세요.

.gitignore

website의 .gitignore에는 다음 항목이 포함되어야 합니다:

.gitignore

# dependencies
/node_modules

# production
/build

# generated files
.docusaurus
.cache-loader

# misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*

README

도큐사우루스 1 웹사이트는 기존 README 파일을 가지고 있을 겁니다. D2의 변경사항을 반영하도록 수정하거나 기본 도큐사우루스 v2 README를 복사할 수 있습니다.

사이트 설정

docusaurus.config.js

siteConfig.js의 이름을 docusaurus.config.js로 변경하세요.

도큐사우루스 2에서는 각 기능(블로그, 문서, 페이지)를 모듈화해서 플러그인으로 분리했습니다. 프리셋은 플러그인 묶음입니다. 하위 호환성을 위해 도큐사우루스 1의 주요 플러그인 대부분을 포함하는 @docusaurus/preset-classic 프리셋을 만들었습니다.

다음 프리셋 설정을 docusaurus.config.js에 추가하세요.

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // website 디렉터리 기준 문서 폴더의 상대 경로입니다.
          path: '../docs',
          // website 디렉터리 기준 사이드바 파일의 상대 경로입니다.
          sidebarPath: require.resolve('./sidebars.json'),
        },
        // ...
      },
    ],
  ],
};

docs 폴더를 website 폴더 안으로 이동하는 것을 권장합니다. 이는 v2의 기본 디렉터리 구조이기도 합니다. docs 디렉터리가 website 안에 있다면 Vercel은 도큐사우루스 프로젝트 배포를 기본 지원합니다. 또한 문서를 웹사이트 안에 두면 문서와 나머지 웹사이트 코드를 하나의 website 디렉터리에 함께 관리할 수 있으므로 일반적으로 더 좋습니다.

도큐사우루스 v1 웹사이트를 마이그레이션할 때 처리 중인 문서 풀 리퀘스트가 있다면 충돌을 방지하기 위해 /docs 폴더를 당분간 원래 위치에 둘 수 있습니다.

siteConfig.js의 각 필드에 대해서는 아래 마이그레이션 가이드를 참고하세요.

변경된 필드

baseUrl, tagline, title, url, favicon, organizationName, projectName, githubHost, scripts, stylesheets

별다른 조치는 필요 없습니다. 해당 설정 필드는 수정되지 않았습니다.

colors

더 이상 사용하지 않습니다. 도큐사우루스 2를 위해 Infima라는 자체 CSS 프레임워크를 만들었습니다. Infima는 CSS 변수를 사용해 테마를 적용합니다. 관련 문서는 아직 준비중이며 이곳에 업데이트할 예정입니다. Infima의 CSS 변수를 재정의하려면 자체 CSS 파일(예: ./src/css/custom.css)을 만들고 @docusaurus/preset-classic의 옵션으로 전달하여 전역으로 가져오세요:

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: [require.resolve('./src/css/custom.css')],
        },
      },
    ],
  ],
};

인피마에서는 각 색상에 7가지 음영 단계를 적용합니다.

/src/css/custom.css

/**
 * 여기서 기본 Infima 변수를 재정의할 수 있습니다.
 * 참고: --ifm- 변수의 전체 목록은 아닙니다.
 */
:root {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: rgb(33, 175, 144);
  --ifm-color-primary-darker: rgb(31, 165, 136);
  --ifm-color-primary-darkest: rgb(26, 136, 112);
  --ifm-color-primary-light: rgb(70, 203, 174);
  --ifm-color-primary-lighter: rgb(102, 212, 189);
  --ifm-color-primary-lightest: rgb(146, 224, 208);
}

선택한 기본 색상의 다양한 음영을 찾으려면 ColorBox 사용을 권장합니다.

또는 다음 도구로 웹사이트에 사용할 다양한 음영을 생성한 뒤 변수를 src/css/custom.css에 복사하세요.

팁

가독성을 위한 기본 색상에 대해 최소한 WCAG AA 레벨 명암비를 목표로 합니다. 도큐사우르스 웹사이트 자체를 사용해 색상 팔레트가 어떻게 보일지 미리 확인합니다. 일반적으로 하나의 색상이 밝은 모드와 어두운 모드에서 모두 작동하지 않기 때문에 어두운 모드에서 대체 팔레트를 사용할 수 있습니다.

기본 색상

배경:

CSS 변수 이름	Hex	색상 보정	색상 대비
--ifm-color-primary-lightest	#3cad6e		Fail 🔴
--ifm-color-primary-lighter	#359962		Fail 🔴
--ifm-color-primary-light	#33925d		Fail 🔴
--ifm-color-primary	#2e8555	0	AA 👍
--ifm-color-primary-dark	#29784c		AA 👍
--ifm-color-primary-darker	#277148		AA 👍
--ifm-color-primary-darkest	#205d3b		AAA 🏅

src/css/custom.css의 변수를 새로운 변수로 바꿉니다.

/src/css/custom.css

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
}

footerIcon, copyright, ogImage, twitterImage, docsSideNavCollapsible

애셋, SEO, 저작권 정보 같은 사이트 메타 정보는 테마에서 처리할 수 있습니다. 이를 변경하려면 docusaurus.config.js의 themeConfig 필드를 사용하세요:

docusaurus.config.js

module.exports = {
  // ...
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta 오픈 소스 로고',
        src: '/img/meta_oss_logo.png',
        href: 'https://opensource.facebook.com/',
      },
      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // 여기에 자체 HTML을 넣을 수도 있습니다.
    },
    image: 'img/docusaurus.png',
    // ...
  },
};

headerIcon, headerLinks

도큐사우루스 1에서는 헤더 아이콘과 헤더 링크가 siteConfig의 루트 필드였습니다:

siteConfig.js

headerIcon: 'img/docusaurus.svg',
headerLinks: [
  { doc: "doc1", label: "Getting Started" },
  { page: "help", label: "Help" },
  { href: "https://github.com/", label: "GitHub" },
  { blog: true, label: "Blog" },
],

이제는 테마에서 2개 필드를 관리합니다.

docusaurus.config.js

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      title: 'Docusaurus',
      logo: {
        alt: '도큐사우루스 로고',
        src: 'img/docusaurus.svg',
      },
      items: [
        {to: 'docs/doc1', label: '시작하기', position: 'left'},
        {to: 'help', label: '도움말', position: 'left'},
        {
          href: 'https://github.com/',
          label: 'GitHub',
          position: 'right',
        },
        {to: 'blog', label: '블로그', position: 'left'},
      ],
    },
    // ...
  },
};

algolia

docusaurus.config.js

module.exports = {
  // ...
  themeConfig: {
    algolia: {
      apiKey: '47ecd3b21be71c5822571b9f59e52544',
      indexName: 'docusaurus-2',
      algoliaOptions: { //... },
    },
    // ...
  },
};

경고

Algolia DocSearch v1 설정(여기에서 확인)을 도큐사우루스 v2에 맞게 업데이트해야 합니다(예시).

지원이 필요한 경우 DocSearch 팀(@shortcuts, @s-pace)에 문의할 수 있습니다. 업데이트 후에는 여러분의 사이트 검색을 복원하기 위해 재크롤링을 작동시킬 수 있습니다(그렇지 않으면 다음 예약된 크롤링 작업을 최대 24시간까지 기다려야 할 수도 있습니다).

blogSidebarCount

더 이상 사용하지 않습니다. 대신 @docusaurus/preset-classic의 블로그 옵션으로 전달하세요:

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          postsPerPage: 10,
        },
        // ...
      },
    ],
  ],
};

cname

더 이상 사용하지 않습니다. 대신 static 폴더에 사용자 정의 도메인이 담긴 CNAME 파일을 만드세요. static 폴더의 파일은 빌드 명령을 실행할 때 build 폴더의 루트로 복사됩니다.

customDocsPath, docsUrl, editUrl, enableUpdateBy, enableUpdateTime

호환성을 깨뜨리는 변경: editUrl은 docs 디렉터리 대신 도큐사우루스 프로젝트(website)를 가리켜야 합니다.

더 이상 사용하지 않습니다. 대신 @docusaurus/preset-classic의 docs 옵션으로 전달하세요:

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // `customDocsPath`에 해당합니다.
          path: 'docs',
          // `editUrl`에 해당하지만 `website/docs` 대신 `website` 디렉터리를 가리켜야 합니다.
          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
          // `docsUrl`에 해당합니다.
          routeBasePath: 'docs',
          // MDX에 전달할 Remark 및 Rehype 플러그인입니다. `markdownOptions`와 `markdownPlugins`를 대체합니다.
          remarkPlugins: [],
          rehypePlugins: [],
          // `enableUpdateBy`에 해당합니다.
          showLastUpdateAuthor: true,
          // `enableUpdateTime`에 해당합니다.
          showLastUpdateTime: true,
        },
        // ...
      },
    ],
  ],
};

gaTrackingId

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        googleAnalytics: {
          trackingID: 'UA-141789564-1',
        },
      },
    ],
  ],
};

gaGtag

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        gtag: {
          trackingID: 'UA-141789564-1',
        },
      },
    ],
  ],
};

삭제된 필드

아래 필드는 모드 더 이상 사용하지 않습니다. 설정 파일에서 삭제되어야 합니다.

• blogSidebarTitle
• cleanUrl - 이제 깔끔한 URL이 기본적으로 사용됩니다.
• defaultVersionShown - 버전 관리 기능은 아직 이식되지 않았습니다. 이전에 버전 관리를 사용하고 있었다면 도큐사우루스 2로 마이그레이션할 수 없습니다. 좀 더 기다려주세요.
• disableHeaderTitle
• disableTitleTagline
• docsSideNavCollapsible은 docsPluginOptions.sidebarCollapsible에서 사용할 수 있으며, 이제 기본적으로 활성화됩니다.
• facebookAppId
• facebookComments
• facebookPixelId
• fonts
• highlight - 이제 highlight.js 대신 Prism을 사용합니다.
• markdownOptions - v2에서는 Remarkable 대신 MDX를 사용합니다. 마크다운 옵션은 Remark/Rehype 플러그인에 맞게 수정해주어야 합니다.
• markdownPlugins - v2에서는 Remarkable 대신 MDX를 사용합니다. 마크다운 플러그인은 Remark/Rehype 플러그인에 맞게 수정해주어야 합니다.
• manifest
• onPageNav - 이제 기본적으로 활성화됩니다.
• separateCss - 위에서 설명한 custom.css와 같은 방식으로 가져올 수 있습니다.
• scrollToTop
• scrollToTopOptions
• translationRecruitingLink
• twitter
• twitterUsername
• useEnglishUrl
• users
• usePrism - 이제 highlight.js 대신 Prism을 사용합니다
• wrapPagesHTML

더 이상 사용하지 않는 설정은 플러그인 필드로 대체될 겁니다. 여러분의 도움이 필요합니다!

Urls

v1에서는 .html 확장자의 유무와 관계없이 모든 페이지에 접근할 수 있었습니다.

아래와 같은 2개 페이지가 있다고 예를 들면

• https://v1.docusaurus.io/docs/en/installation
• https://v1.docusaurus.io/docs/en/installation.html

cleanUrl의 값에 따른 동작은 다음과 같았습니다:

• true: 링크가 /installation을 가리킵니다
• false: 링크가 /installation.html을 가리킵니다

v2에서는 기본 정규 페이지가 /installation.html이 아닌 /installation입니다.

v1에서 cleanUrl: false를 사용했다면 사람들이 /installation.html 링크를 게시했을 수 있습니다.

SEO와 연결되지 않는 링크를 만들지 않으려면 호스팅 제공업체 쪽 서버 측 리다이렉트 규칙을 설정해주어야 합니다.

해결 방법으로 @docusaurus/plugin-client-redirects를 사용해 /installation.html에서 /installation로 클라이언트 측 리디렉션을 만들 수 있습니다.

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-client-redirects',
      {
        fromExtensions: ['html'],
      },
    ],
  ],
};

페이지의 정규 URL에 .html 확장자를 유지하려면 문서의 프런트 매터에 slug: installation.html을 선언하면 됩니다.

컴포넌트

사이드바

이전 버전에서는 중첩된 사이드 카테고리를 사용할 수 없으며 사이드바 카테고리는 문서 ID만 포함할 수 있었습니다. 하지만 v2는 사이드바를 제한 없이 중첩할 수 있으며 문서 외에도 여러 유형의 사이드바 항목을 지원합니다.

카테고리 타입이 포함된 경우 사이드바를 마이그레이션 대상에 포함해야 합니다. subcategory를 category로, ids를 items로 이름을 변경하세요.

sidebars.json

{
- type: 'subcategory',
+ type: 'category',
  label: 'My Example Subcategory',
+ items: ['doc1'],
- ids: ['doc1']
},

바닥글

website/core/Footer.js는 더 이상 필요하지 않습니다. 도큐사우루스가 제공하는 기본 푸터를 수정하려면 스위즐링하세요:

npm

npm run swizzle @docusaurus/theme-classic Footer

Yarn

yarn swizzle @docusaurus/theme-classic Footer

pnpm

pnpm run swizzle @docusaurus/theme-classic Footer

Bun

bun run swizzle @docusaurus/theme-classic Footer

테마에서 사용하는 현재 <Footer /> 컴포넌트가 사이트 루트의 src/theme/Footer 디렉터리로 복사됩니다. 이 컴포넌트를 편집하여 원하는 대로 변경할 수 있습니다.

로고를 왼쪽으로 옮기기 위해 바닥글을 변경하지는 마세요. v2에서 로고는 아래쪽으로 옮겨졌습니다. docusaurus.config.js에서 themeConfig.footer로 푸터를 설정하면 됩니다:

module.exports = {
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta Open Source Logo',
        src: '/img/meta_oss_logo.png',
        href: 'https://opensource.facebook.com',
      },
    },
  },
};

페이지

도큐사우루스 2 페이지의 동작 방식은 페이지 만들기를 참고하세요. 해당 문서를 읽은 뒤 v1의 pages/en 파일을 src/pages로 이동해야 한다는 점에 유의하세요.

도큐사우루스 v1에서 페이지는 siteConfig 객체를 props로 받았습니다.

도큐사우루스 v2에서는 대신 useDocusaurusContext에서 siteConfig 객체를 가져옵니다.

v2에서는 각 페이지에 테마 레이아웃을 적용해야 합니다. 레이아웃 컴포넌트는 메타데이터 속성을 사용할 수 있습니다.

v2에서는 CompLibrary가 더 이상 지원되지 않으므로 리액트 컴포넌트를 직접 작성하거나 Infima 스타일을 사용해야 합니다(문서는 곧 제공될 예정입니다. 양해 부탁드립니다! 그 동안은 V2 웹 사이트를 참고하거나 https://infima.dev/에서 스타일이 적용되는 방식을 참고해주세요).

ES6 import/export를 사용해 CommonJS를 옮길 수 있습니다.

아래는 전형적인 도큐사우루스 v2 페이지입니다.

import React from 'react';
import Link from '@docusaurus/Link';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import Layout from '@theme/Layout';

const MyPage = () => {
  const {siteConfig} = useDocusaurusContext();
  return (
    <Layout title={siteConfig.title} description={siteConfig.tagline}>
      <div className="hero text--center">
        <div className="container ">
          <div className="padding-vert--md">
            <h1 className="hero__title">{siteConfig.title}</h1>
            <p className="hero__subtitle">{siteConfig.tagline}</p>
          </div>
          <div>
            <Link
              to="/docs/get-started"
              className="button button--lg button--outline button--primary">
              시작하기
            </Link>
          </div>
        </div>
      </div>
    </Layout>
  );
};

export default MyPage;

아래 코드에서 다양한 페이지 마이그레이션 방식을 참조할 수 있습니다.

• 인덱스 페이지 - Flux(권장), 도큐사우루스 2, Hermes
• 도움말/지원 페이지 - 도큐사우루스 2, Flux

콘텐츠

AUTOGENERATED_TABLE_OF_CONTENTS 대체

이 기능은 인라인 목차로 대체되었습니다

마크다운 구문을 MDX에 호환되도록 업데이트

도큐사우루스 2에서는 마크다운 구문이 MDX로 변경되었습니다. 때문에 업데이트하는 기존 문서에 일부 구문이 동작하지 않을 수 있습니다. 대표적인 예로, HTML에서는 유효한 <img>와 <br> 같은 태그를 이제 명시적으로 닫아야 합니다( <img/>와 <br/>). MDX 문서에서 모든 태그는 유효한 JSX 이어야 합니다.

프런트 매터는 gray-matter로 파싱됩니다. 프런트 매터에 : 같은 특수 문자를 사용한다면 이제 따옴표로 감싸야 합니다: title: Part 1: my part1 title → title: "Part 1: my part1 title".

팁: HTML to JSX 같은 온라인 도구를 사용하면 마이그레이션이 더 쉬워집니다.

프로그래밍 언어 별 코드 탭

다중 언어 지원 코드 블록 섹션을 참고하세요.

프런트 매터

블로그의 도큐사우루스 프런트 매터 형식이 문서와 일치하도록 카멜표기법(camelCase)에서 스네이크 표기법(snake_case)으로 변경됐습니다.

authorFBID와 authorTwitter 필드는 더 이상 지원되지 않습니다. 이 필드들은 작성자의 프로필 이미지를 생성하는 데만 사용되었으며, 이제 authors 필드로 처리할 수 있습니다.

배포

GitHub Pages에서 사용하는 CNAME 파일은 더 이상 생성되지 않으므로 사용자 정의 도메인을 사용한다면 /static/CNAME에 직접 만들어 두어야 합니다.

블로그 RSS 피드는 이제 /blog/feed.xml 대신 /blog/rss.xml에서 제공됩니다. 사용자가 이미 구독하고 있는 서비스를 계속 유지하고 싶다면 서버 측 리다이렉트를 설정할 수 있습니다.

사이트 테스트하기

마이그레이션 이후에 디렉터리 구조는 아래와 같은 형태가 됩니다.

my-project
├── docs
└── website
    ├── blog
    ├── src
    │   ├── css
    │   │   └── custom.css
    │   └── pages
    │       └── index.js
    ├── package.json
    ├── sidebars.json
    ├── .gitignore
    ├── docusaurus.config.js
    └── static

개발 서버를 시작하고 에러를 확인하고 수정하세요.

npm

cd website
npm start

Yarn

cd website
yarn start

pnpm

cd website
pnpm start

Bun

cd website
bun start

제품 빌드도 정상적으로 처리되는지 확인해야 합니다.

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build

Bun

bun run build