수동으로 마이그레이션 처리
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
. 때문에 이에 대한 종속성이 추가되어야 합니다.
{
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:
{
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy"
// ...
}
}
A typical Docusaurus 2 package.json
may look like this:
{
"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:
# 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
.
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
:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
인피마에서는 각 색상에 7가지 음영 단계를 적용합니다.
/**
* 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
.
가독성을 위한 기본 색상에 대해 최소한 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;
}