Version: 2.0.0-beta.3

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

자동으로 마이그레이션 처리 이후 누락된 부분 또는 마이그레이션 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",  }}

tip

최신 도큐사우루스 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": "^16.8.4",    "react-dom": "^16.8.4"  },  "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 디렉터리가 있다면 나우(Now)를 사용해 도큐사우루스 프로젝트 배포에 바로 적용할 수 있습니다. 하나의 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 파일에 직접 반영할 수 있습니다.

Primary Color:

CSS Variable Name	Hex	Adjustment
`--ifm-color-primary-lightest`	`#80aaef`
`--ifm-color-primary-lighter`	`#5a91ea`
`--ifm-color-primary-light`	`#4e89e8`
`--ifm-color-primary`	`#3578e5`	0
`--ifm-color-primary-dark`	`#1d68e1`
`--ifm-color-primary-darker`	`#1b62d4`
`--ifm-color-primary-darkest`	`#1751af`

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

--ifm-color-primary: #3578e5;--ifm-color-primary-dark: #1d68e1;--ifm-color-primary-darker: #1b62d4;--ifm-color-primary-darkest: #1751af;--ifm-color-primary-light: #4e89e8;--ifm-color-primary-lighter: #5a91ea;--ifm-color-primary-lightest: #80aaef;

`footerIcon`, `copyright`, `ogImage`, `twitterImage`, `docsSideNavCollapsible`#

애셋, SEO, 저작권 정보 같은 사이트 메타 정보는 테마에서 처리할 수 있습니다. docusaurus.config.js에서 themeConfig 필드를 원하는 값으로 수정합니다.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    footer: {      logo: {        alt: 'Facebook Open Source Logo',        src: 'https://docusaurus.io/img/oss_logo.png',        href: 'https://opensource.facebook.com/',      },      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // HTML 코드로 설정할 수도 있습니다.    },    image: 'img/docusaurus.png',    // `docsSideNavCollapsible`과 같음.    sidebarCollapsible: false,    // ...  },};

`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: { //... },    },    // ...  },};

caution

알골리아 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/master/website',          //`docsUrl`과 같음.          routeBasePath: 'docs',          // MDX로 전달할 Remark, Rehype 플러그인. `markdownOptions`와 `markdownPlugins`를 대체함.          remarkPlugins: [],          rehypePlugins: [],          // `enableUpdateBy`와 같음.          showLastUpdateAuthor: true,          // `enableUpdateTime`과 같음.          showLastUpdateTime: true,        },        // ...      },    ],  ],};

`gaTrackingId`#

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    googleAnalytics: {      trackingID: 'UA-141789564-1',    },    // ...  },};

`gaGtag`#

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    gtag: {      trackingID: 'UA-141789564-1',    },    // ...  },};

삭제된 필드#

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

blogSidebarTitle
cleanUrl - 간편 URL(Clean URL)은 기본값으로 설정됩니다.
defaultVersionShown - 버전 관리는 아직 마이그레이션을 지원하지 않습니다. 이전에 버전 관리를 사용하고 있었다면 도큐사우루스 2로 마이그레이션할 수 없습니다. 좀 더 기다려주세요.
disableHeaderTitle
disableTitleTagline
docsSideNavCollapsible은 themeConfig.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개 페이지가 있다고 예를 들면

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
Yarn

npm run swizzle @docusaurus/theme-classic Footer

yarn run swizzle @docusaurus/theme-classic Footer

이렇게 하면 테마에서 사용하는 <Footer /> 컴포넌트가 사이트 루트 디렉터리 아래 src/theme/Footer 디렉터리로 복사됩니다. 그리고나서 컴포넌트를 수정할 수 있습니다.

로고를 왼쪽으로 옮기기 위해 바닥글을 변경하지는 마세요. v2에서 로고는 아래쪽으로 옮겨졌습니다. 바닥글 설정은 docusaurus.config.js에서 themeConfig.footer 항목을 수정해주어야 합니다.

module.exports = {  themeConfig: {    footer: {      logo: {        alt: 'Facebook Open Source Logo',        src: 'img/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 같은 온라인 도구를 사용해 쉽게 코드를 변환할 수 있습니다.

프로그래밍 언어 별 코드 탭#

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

프런트 매터#

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

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

배포#

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

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

yarn build

프로젝트 설정#

package.json#

스코프 패키지명#

tip

CLI 명령어#

build 디렉터리에 대한 참조 업데이트#

.gitignore#

README#

사이트 설정#

docusaurus.config.js#

변경된 필드#

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

colors#

footerIcon, copyright, ogImage, twitterImage, docsSideNavCollapsible#

headerIcon, headerLinks#

algolia#

caution

blogSidebarCount#

cname#

customDocsPath, docsUrl, editUrl, enableUpdateBy, enableUpdateTime#

gaTrackingId#

gaGtag#

삭제된 필드#

Urls#

컴포넌트#

사이드바#

바닥글#

페이지#

콘텐츠#

AUTOGENERATED_TABLE_OF_CONTENTS 대체#

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

프로그래밍 언어 별 코드 탭#

프런트 매터#

배포#

사이트 테스트하기#

`package.json`#

`build` 디렉터리에 대한 참조 업데이트#

`.gitignore`#

`README`#

`docusaurus.config.js`#

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

`colors`#

`footerIcon`, `copyright`, `ogImage`, `twitterImage`, `docsSideNavCollapsible`#

`headerIcon`, `headerLinks`#

`algolia`#

`blogSidebarCount`#

`cname`#

`customDocsPath`, `docsUrl`, `editUrl`, `enableUpdateBy`, `enableUpdateTime`#

`gaTrackingId`#

`gaGtag`#