수동으로 마이그레이션 처리
자동으로 마이그레이션 처리 이후 누락된 부분 또는 마이그레이션 CLI 처리 중 문제가 생긴 부분은 수동으로 처리해주어야 합니다.
프로젝트 설정
package.json
스코프 패키지명
도큐사우루스 2에서는 스코프 패키지명을 사용합니다.
docusaurus
→@docusaurus/core
이를 통해 공식적으로 도큐사우루스에서 제공하는 패키지와 커뮤니티에서 만든 패키지를 구별할 수 있습니다. 즉 도큐사우루스 공식 패키지는 모두 @docusaurus/
아래에 네임스페이스가 지정됩니다.
도큐사우루스 1에서는 기본으로 제공되던 문서 사이트 기능도 이제는 @docusaurus/preset-classic
을 통해 지원합니다. 때문에 이에 대한 종속성이 추가되어야 합니다.
{
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"
항목 내용을 아래와 같이 수정해주세요.
{
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy"
// ...
}
}
일반적인 도큐사우루스 2 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
파일에는 아래와 같은 내용이 설정되어 있어야 합니다.
# 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
에 아래 사전 설정을 추가해주세요.
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
에 옵션으로 전달해 전역에서 사용할 수 있도록 가져옵니다.
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
인피마에서는 각 색상에 7가지 음영 단계를 적용합니다.
/**
* 기본 인피마 변수 설정을 재설정할 수 있습니다.
* 참고: 아래 목록이 --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
의 변수를 새로운 변수로 바꿉니다.
: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;
}