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

자동으로 마이그레이션 처리 이후 누락된 부분 또는 마이그레이션 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 디렉터리가 제대로 작성됐는지 확인해보세요.

깃허브 페이지에 배포한다면 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 파일을 가지고 있을 겁니다. 도큐사우루스 2 변경 내용을 반영해 수정하거나 기본 도큐사우루스 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 디렉터리 기준으로 docs 디렉터리의 상대 경로
          path: '../docs',
          // website 디렉터리 기준으로 사이드바 파일의 상대 경로
          sidebarPath: require.resolve('./sidebars.json'),
        },
        // ...
      },
    ],
  ],
};

docs 디렉터리는 website 디렉터리 아래로 이동하는 것을 권장합니다. v2의 기본 디렉터리 구조입니다. website 디렉터리 아래에 docs 디렉터리가 있다면 Vercel을 사용해 도큐사우루스 프로젝트 배포에 바로 적용할 수 있습니다. 하나의 website 디렉터리 안에 문서와 웹 사이트에서 사용하는 다른 코드가 같이 있을 수 있게 website 디렉터리 안에 docs 디렉터리를 가지고 있는 것이 좋습니다.

도큐사우루스 v1 웹 사이트를 이전하는 동안 처리되고 있는 풀 리퀘스트가 있다면 충돌을 방지하기 위해 임시적으로 /docs 디렉터리를 원래 위치에 놓아둘 수도 있습니다.

siteConfig.js의 각 항목에 대해서는 아래 설명을 참고하세요.

변경된 필드

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

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

colors

더 이상 사용하지 않습니다. 테마 설정 시 CSS 변수를 사용하는 Infima를 활용할 수 있도록 도큐사우루스 2 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

/**
 * 기본 인피마 변수 설정을 재설정할 수 있습니다.
 * 참고: 아래 목록이 --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 Open Source Logo',
        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: '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

알골리아 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 디렉터리가 아닌 도큐사우루스 프로젝트(웹 사이트)를 가리키고 있어야 합니다.

더 이상 사용하지 않습니다. 대신 @docusaurus/preset-classic에서 옵션으로 설정합니다.

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(Clean 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'],
      },
    ],
  ],
};

.html 확장자를 페이지의 표준 URL로 유지하고 싶다면 문서에서 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는 더 이상 필요하지 않습니다. 도큐사우루스에서 제공하는 기본 바닥글을 수정하고 싶다면 swizzle 명령을 사용하세요.

npm

npm run swizzle @docusaurus/theme-classic Footer

Yarn

yarn swizzle @docusaurus/theme-classic Footer

pnpm

pnpm 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 오브젝트를 받았습니다.

도큐사우루스 v2에서는 useDocusaurusContext에서 siteConfig 오브젝트를 가져올 수 있습니다.

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

CompLibrary는 v2에서 더 이상 사용하지 않습니다. 리액트 컴포넌트를 직접 작성하거나 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">
              Get started
            </Link>
          </div>
        </div>
      </div>
    </Layout>
  );
};

export default MyPage;

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

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

콘텐츠

AUTOGENERATED_TABLE_OF_CONTENTS 대체

해당 기능은 목차 단락으로 대체됐습니다.

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

도큐사우루스 2에서 마크다운 구문은 MDX로 변경됐습니다. 때문에 업데이트하는 기존 문서에 일부 구문이 동작하지 않을 수 있습니다. 가장 일반적인 예는 <img>나 <br> 처럼 HTML에서 유효한 태그의 자체 닫기입니다. 이제는 명시적으로 닫아주어야 합니다(<img/>, <br/>). MDX 문서에서 모든 태그는 유효한 JSX 이어야 합니다.

프런트 매터는 gray-matter를 사용해 구문을 분석합니다. 프런트 매터에서 : 같은 특별한 문자를 사용했다면 다음과 같이 인용부호를 추가해주어야 합니다. title: Part 1: my part1 title → title: "Part 1: my part1 title"

참고: HTML to JSX 같은 온라인 도구를 사용해 쉽게 코드를 변환할 수 있습니다.

프로그래밍 언어 별 코드 탭

코드 블록 내에서 여러 프로그래밍 언어 지원하기 문서를 참고하세요.

Front matter

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

authorFBID와 authorTwitter 필드는 더 이상 사용하지 않습니다. authors 필드를 통해 처리되는 작성자의 프로필 이미지를 만드는 용도로만 사용됩니다.

배포

깃허브 페이지에서 사용하는 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

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

cd website
yarn start

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

yarn build