메인 컨텐츠로 이동
Version: 2.0.0-beta.0

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

자동으로 마이그레이션 처리 이후 누락된 부분 또는 마이그레이션 CLI 처리 중 문제가 생긴 부분은 수동으로 처리해주어야 합니다.

프로젝트 설정#

package.json#

스코프 패키지명#

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

  • docusaurus -> @docusaurus/core

이를 통해 공식적으로 도큐사우루스에서 제공하는 패키지와 커뮤니티에서 만든 패키지를 구별할 수 있습니다. 즉 도큐사우루스 공식 패키지는 모두 @docusaurus/ 아래에 네임스페이스가 지정됩니다.

도큐사우루스 1에서는 기본으로 제공되던 문서 사이트 기능도 이제는 @docusaurus/preset-classic을 통해 지원합니다. 때문에 이에 대한 종속성이 추가되어야 합니다.

package.json
{
dependencies: {
- "docusaurus": "^1.x.x",
+ "@docusaurus/core": "^2.0.0-alpha.48",
+ "@docusaurus/preset-classic": "^2.0.0-alpha.48",
}
}
tip

최신 도큐사우루스 2 버전을 확인하고 해당 버전으로 설정해주세요(next 태그로 작성된 버전입니다).

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-alpha.66",
"@docusaurus/preset-classic": "^2.0.0-alpha.66",
"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 파일에 직접 반영할 수 있습니다.

CSS Variable NameHexAdjustment
--ifm-color-primary-lightest#80aaef
--ifm-color-primary-lighter#5a91ea
--ifm-color-primary-light#4e89e8
--ifm-color-primary#3578e50
--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: { //... },
},
// ...
},
};

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#

주의: editUrldocs 디렉터리가 아닌 도큐사우루스 프로젝트(웹 사이트)를 가리키고 있어야 합니다.

더 이상 사용하지 않습니다. 대신 @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
  • docsSideNavCollapsiblethemeConfig.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는 제약없이 중첩된 사이드바를 구성할 수 있고 문서 외에 다양한 형태의 사이드바 아이템을 지원합니다.

카테고리 타입이 포함된 경우 사이드바를 마이그레이션 대상에 포함해야 합니다. subcategorycategoryidsitems으로 변경합니다.

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

바닥글#

website/core/Footer.js는 더 이상 필요하지 않습니다. 도큐사우루스에서 제공하는 기본 바닥글을 수정하고 싶다면 swizzle 명령을 사용하세요.

npm 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;

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

콘텐츠#

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)으로 변경됐습니다.

authorFBIDauthorTwitter 필드는 더 이상 사용하지 않습니다. 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 website
yarn start

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

yarn build