설정
Check the docusaurus.config.js
API reference for an exhaustive list of options.
도큐사우루스는 자체적인 설정 환경을 가지고 있습니다. 여러분의 각 사이트에서 사용할 정보는 한 곳에 모아 놓는 것을 권장합니다. 그렇게 하면 우리는 설정 파일의 필드를 보호하고 각 사이트에서 데이터 객체에 접근할 수 있도록 허용해줄 수 있습니다.
적절하게 구성된 docusaurus.config.js
파일은 여러분 뿐 아니라 협업자, 오픈소스 기여자들이 문서 작성에 집중할 수 있도록 도와줍니다. 물론 필요한 경우 개별 설정을 변경할 수 있습니다.
Syntax to declare docusaurus.config.js
The docusaurus.config.js
file is run in Node.js and should export either:
- a config object
- a function that creates the config object
The docusaurus.config.js
file supports:
Constraints:
- Required: use
export default /* your config*/
(ormodule.exports
to export your Docusaurus config - Optional: use
import Lib from 'lib'
(orrequire('lib')
) to import Node.js packages
Docusaurus gives us the ability to declare its configuration in various equivalent ways, and all the following config examples lead to the exact same result:
export default {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
module.exports = {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
import type {Config} from '@docusaurus/types';
export default {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
} satisfies Config;
const config = {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
export default config;
export default function configCreator() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
}
export default async function createConfigAsync() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
}
Using an async config creator can be useful to import ESM-only modules (notably most Remark plugins). It is possible to import such modules thanks to dynamic imports:
export default async function createConfigAsync() {
// Use a dynamic import instead of require('esm-lib')
const lib = await import('lib');
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// rest of your site config...
};
}
docusaurus.config.js
파일에서 무엇을 설정하나요?
사이트의 내용은 직접 작성해야 하지만 docusaurus.config.js
파일을 처음부터 새로 작성할 필요는 없습니다. 모든 템플릿은 공통으로 사용하는 옵션에 대한 기본값을 포함하는 docusaurus.config.js
파일을 함께 제공합니다.
하지만 설정 항목이 어떤 식으로 설계됐고 반영되고 있는지 알아야 하는 경우 필요한 유용한 정보를 정리했습니다.
도큐사우루스에서 사용하는 각 설정은 아래와 같이 구분할 수 있습니다.
사이트 메타데이터
사이트 메타데이터는 title
, url
, baseUrl
, favicon
같이 사이트 전체에서 필수로 사용하는 메타데이터를 포함합니다.
메타데이터는 사이트 제목, 브라우저 탭 아이콘, 소셜 공유(페이스북, 트위터)를 위한 정보로 사용하거나 사이트에서 사용할 파일에 대한 정확한 경로를 생성하기 위해 사용합니다.
배포 설정
projectName
이나 organizationName
배포 설정 그리고 deploymentBranch
과 같은 추가적인 배포 설정은 deploy
명령으로 사이트를 배포할 때 사용됩니다.
배포 설정 시에는 배포 가이드를 먼저 참고하기를 권장합니다.
테마, 플러그인, 프리셋 설정
여러분의 사이트에서 themes
, plugins
, presets
필드 항목에 설정한 themes, plugins, presets 목록은 모두 다를 수 있습니다. 대부분은 npm 패키지로 제공되는 것들입니다.
export default {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};
도큐사우루스는 모듈 약식 표기를 지원하므로 위의 구성을 다음과 같이 단순하게 처리할 수 있습니다.
export default {
// ...
plugins: ['content-blog', 'content-pages'],
themes: ['classic'],
};
로컬 디렉터리에서 항목을 가져오게 할 수도 있습니다.
import path from 'path';
export default {
// ...
themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};
플러그인이나 테마 옵션을 설정할 때 이름을 바로 지정하지 않고 이름과 옵션 객체를 포함한 배열로 지정할 수도 있습니다.
export default {
// ...
plugins: [
[
'content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'content-pages',
],
};
플러그인이나 테마 옵션을 기본 제공되는 프리셋으로 지정하려면 presets
항목에 해당 옵션을 지정합니다. 예를 들어 아래 설정에서 docs
에서는 @docusaurus/plugin-content-docs
를 그리고 theme
는 @docusaurus/theme-classic
을 프리셋으로 사용합니다.
export default {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
theme: {
customCss: ['./src/css/custom.css'],
},
},
],
],
};
presets: [['classic', {...}]]
약식 표기는 잘 동작합니다.