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

This manual migration process should be run after the automated migration process, to complete the missing parts, or debug issues in the migration CLI output.

Project setup

package.json

Scoped package names

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

• docusaurus → @docusaurus/core

이를 통해 공식적으로 도큐사우루스에서 제공하는 패키지와 커뮤니티에서 만든 패키지를 구별할 수 있습니다. In another words, all Docusaurus' official packages are namespaced under @docusaurus/.

Meanwhile, the default doc site functionalities provided by Docusaurus 1 are now provided by @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",
  }
}

팁

Please use the most recent Docusaurus 2 version, which you can check out here (using the latest tag).

CLI commands

Meanwhile, CLI commands are renamed to docusaurus <command> (instead of docusaurus-command).

The "scripts" section of your package.json should be updated as follows:

package.json

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

A typical Docusaurus 2 package.json may look like this:

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"
    ]
  }
}

Update references to the build directory

In Docusaurus 1, all the build artifacts are located within website/build/<PROJECT_NAME>.

In Docusaurus 2, it is now moved to just website/build. Make sure that you update your deployment configuration to read the generated files from the correct build directory.

If you are deploying to GitHub pages, make sure to run yarn deploy instead of yarn publish-gh-pages script.

.gitignore

The .gitignore in your website should contain:

.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 파일을 가지고 있을 겁니다. You can modify it to reflect the D2 changes, or copy the default Docusaurus v2 README.

Site configurations

docusaurus.config.js

Rename siteConfig.js to docusaurus.config.js.

도큐사우루스 2에서는 각 기능(블로그, 문서, 페이지)를 모듈화해서 플러그인으로 분리했습니다. Presets are bundles of plugins and for backward compatibility we built a @docusaurus/preset-classic preset which bundles most of the essential plugins present in Docusaurus 1.

Add the following preset configuration to your docusaurus.config.js.

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // Docs folder path relative to website dir.
          path: '../docs',
          // Sidebars file relative to website dir.
          sidebarPath: require.resolve('./sidebars.json'),
        },
        // ...
      },
    ],
  ],
};

We recommend moving the docs folder into the website folder and that is also the default directory structure in v2. Vercel supports Docusaurus project deployments out-of-the-box if the docs directory is within the website. It is also generally better for the docs to be within the website so that the docs and the rest of the website code are co-located within one website directory.

If you are migrating your Docusaurus v1 website, and there are pending documentation pull requests, you can temporarily keep the /docs folder to its original place, to avoid producing conflicts.

Refer to migration guide below for each field in siteConfig.js.

Updated fields

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

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

colors

더 이상 사용하지 않습니다. We wrote a custom CSS framework for Docusaurus 2 called Infima which uses CSS variables for theming. 관련 문서는 아직 준비중이며 이곳에 업데이트할 예정입니다. To overwrite Infima's CSS variables, create your own CSS file (e.g. ./src/css/custom.css) and import it globally by passing it as an option to @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

/**
 * You can override the default Infima variables here.
 * Note: this is not a complete list of --ifm- variables.
 */
: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);
}

We recommend using ColorBox to find the different shades of colors for your chosen primary color.

Alternatively, use the following tool to generate the different shades for your website and copy the variables into src/css/custom.css.

팁

Aim for at least WCAG-AA contrast ratio for the primary color to ensure readability. Use the Docusaurus website itself to preview how your color palette would look like. You can use alternative palettes in dark mode because one color doesn't usually work in both light and dark mode.

Primary Color:

Background:

CSS Variable Name	Hex	Adjustment	Contrast Rating
--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 🏅

Replace the variables in src/css/custom.css with these new variables.

/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, 저작권 정보 같은 사이트 메타 정보는 테마에서 처리할 수 있습니다. To customize them, use the themeConfig field in your docusaurus.config.js:

docusaurus.config.js

module.exports = {
  // ...
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta Open Source Logo',
        src: '/img/meta_oss_logo.png',
        href: 'https://opensource.facebook.com/',
      },
      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here.
    },
    image: 'img/docusaurus.png',
    // ...
  },
};

headerIcon, headerLinks

In Docusaurus 1, header icon and header links were root fields in 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: 'Docusaurus Logo',
        src: 'img/docusaurus.svg',
      },
      items: [
        {to: 'docs/doc1', label: 'Getting Started', position: 'left'},
        {to: 'help', label: 'Help', position: 'left'},
        {
          href: 'https://github.com/',
          label: 'GitHub',
          position: 'right',
        },
        {to: 'blog', label: 'Blog', position: 'left'},
      ],
    },
    // ...
  },
};

algolia

docusaurus.config.js

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

warning

Your Algolia DocSearch v1 config (found here) should be updated for Docusaurus v2 (example).

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

blogSidebarCount

더 이상 사용하지 않습니다. Pass it as a blog option to @docusaurus/preset-classic instead:

docusaurus.config.js

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

cname

더 이상 사용하지 않습니다. Create a CNAME file in your static folder instead with your custom domain. Files in the static folder will be copied into the root of the build folder during execution of the build command.

customDocsPath, docsUrl, editUrl, enableUpdateBy, enableUpdateTime

BREAKING: editUrl should point to (website) Docusaurus project instead of docs directory.

더 이상 사용하지 않습니다. Pass it as an option to @docusaurus/preset-classic docs instead:

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // Equivalent to `customDocsPath`.
          path: 'docs',
          // Equivalent to `editUrl` but should point to `website` dir instead of `website/docs`.
          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
          // Equivalent to `docsUrl`.
          routeBasePath: 'docs',
          // Remark and Rehype plugins passed to MDX. Replaces `markdownOptions` and `markdownPlugins`.
          remarkPlugins: [],
          rehypePlugins: [],
          // Equivalent to `enableUpdateBy`.
          showLastUpdateAuthor: true,
          // Equivalent to `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',
        },
      },
    ],
  ],
};

Removed fields

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

• blogSidebarTitle
• cleanUrl - Clean URL is used by default now.
• defaultVersionShown - Versioning is not ported yet. 이전에 버전 관리를 사용하고 있었다면 도큐사우루스 2로 마이그레이션할 수 없습니다. 좀 더 기다려주세요.
• disableHeaderTitle
• disableTitleTagline
• docsSideNavCollapsible is available at docsPluginOptions.sidebarCollapsible, and this is turned on by default now.
• facebookAppId
• facebookComments
• facebookPixelId
• fonts
• highlight - We now use Prism instead of highlight.js.
• markdownOptions - We use MDX in v2 instead of Remarkable. 마크다운 옵션은 Remark/Rehype 플러그인에 맞게 수정해주어야 합니다.
• markdownPlugins - We use MDX in v2 instead of Remarkable. 마크다운 플러그인은 Remark/Rehype 플러그인에 맞게 수정해주어야 합니다.
• manifest
• onPageNav - This is turned on by default now.
• separateCss - It can imported in the same manner as custom.css mentioned above.
• scrollToTop
• scrollToTopOptions
• translationRecruitingLink
• twitter
• twitterUsername
• useEnglishUrl
• users
• usePrism - We now use Prism instead of highlight.js
• wrapPagesHTML

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

Urls

In v1, all pages were available with or without the .html extension.

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

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

If cleanUrl was:

• true: links would target /installation
• false: links would target /installation.html

In v2, by default, the canonical page is /installation, and not /installation.html.

If you had cleanUrl: false in v1, it's possible that people published links to /installation.html.

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

As an escape hatch, you could use @docusaurus/plugin-client-redirects to create client-side redirects from /installation.html to /installation.

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

If you want to keep the .html extension as the canonical URL of a page, docs can declare a slug: installation.html front matter.

Components

Sidebar

이전 버전에서는 중첩된 사이드 카테고리를 사용할 수 없으며 사이드바 카테고리는 문서 ID만 포함할 수 있었습니다. However, v2 allows infinite nested sidebar and we have many types of Sidebar Item other than document.

카테고리 타입이 포함된 경우 사이드바를 마이그레이션 대상에 포함해야 합니다. Rename subcategory to category and ids to items.

sidebars.json

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

Footer

website/core/Footer.js is no longer needed. If you want to modify the default footer provided by Docusaurus, swizzle it:

npm

npm run swizzle @docusaurus/theme-classic Footer

Yarn

yarn swizzle @docusaurus/theme-classic Footer

pnpm

pnpm run swizzle @docusaurus/theme-classic Footer

This will copy the current <Footer /> component used by the theme to a src/theme/Footer directory under the root of your site, you may then edit this component for customization.

로고를 왼쪽으로 옮기기 위해 바닥글을 변경하지는 마세요. v2에서 로고는 아래쪽으로 옮겨졌습니다. Just configure the footer in docusaurus.config.js with themeConfig.footer:

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

Pages

Please refer to creating pages to learn how Docusaurus 2 pages work. After reading that, notice that you have to move pages/en files in v1 to src/pages instead.

In Docusaurus v1, pages received the siteConfig object as props.

In Docusaurus v2, get the siteConfig object from useDocusaurusContext instead.

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

CompLibrary is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! 그 동안은 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">
              Get started
            </Link>
          </div>
        </div>
      </div>
    </Layout>
  );
};

export default MyPage;

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

• Index page - Flux (recommended), Docusaurus 2, Hermes
• Help/Support page - Docusaurus 2, Flux

Content

Replace AUTOGENERATED_TABLE_OF_CONTENTS

This feature is replaced by inline table of content

Update Markdown syntax to be MDX-compatible

In Docusaurus 2, the Markdown syntax has been changed to MDX. 때문에 업데이트하는 기존 문서에 일부 구문이 동작하지 않을 수 있습니다. A common example is self-closing tags like <img> and <br> which are valid in HTML would have to be explicitly closed now ( <img/> and <br/>). MDX 문서에서 모든 태그는 유효한 JSX 이어야 합니다.

Front matter is parsed by gray-matter. If your front matter use special characters like :, you now need to quote it: title: Part 1: my part1 title → title: "Part 1: my part1 title".

Tips: You might want to use some online tools like HTML to JSX to make the migration easier.

Language-specific code tabs

Refer to the multi-language support code blocks section.

Front matter

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

The fields authorFBID and authorTwitter have been deprecated. They are only used for generating the profile image of the author which can be done via the authors field.

Deployment

The CNAME file used by GitHub Pages is not generated anymore, so be sure you have created it in /static/CNAME if you use a custom domain.

The blog RSS feed is now hosted at /blog/rss.xml instead of /blog/feed.xml. 사용자가 이미 구독하고 있는 서비스를 계속 유지하고 싶다면 서버 측 리다이렉트를 설정할 수 있습니다.

Test your site

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

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

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

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build