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

docusaurus.config.js

개요

docusaurus.config.js 파일에는 사이트에 필요한 설정을 담고 있습니다. 설정 파일은 사이트 루트 디렉터리에 있습니다.

It usually exports a site configuration object:

docusaurus.config.js
module.exports = {
// site config...
};
Config files also support config creator functions and async code.
docusaurus.config.js
module.exports = function configCreator() {
return {
// site config...
};
};
docusaurus.config.js
module.exports = async function configCreatorAsync() {
return {
// site config...
};
};
docusaurus.config.js
module.exports = Promise.resolve({
// site config...
});

필수 입력 항목

title

  • Type: string

웹 사이트 타이틀을 설정합니다. Will be used in metadata and as browser tab title.

docusaurus.config.js
module.exports = {
title: 'Docusaurus',
};

url

  • Type: string

웹 사이트의 URL을 설정합니다. 이 설정은 최상위 호스트 이름으로 처리되기도 합니다. 예를 들어 https://facebook.github.iohttps://facebook.github.io/metro/의 URL이 되고 https://docusaurus.iohttps://docusaurus.io의 URL이 됩니다. baseUrl와 같이 사용되는 항목입니다.

docusaurus.config.js
module.exports = {
url: 'https://docusaurus.io',
};

baseUrl

  • Type: string

사이트의 Base URL을 설정합니다. Can be considered as the path after the host. For example, /metro/ is the base URL of https://facebook.github.io/metro/. 경로가 없는 URL이라면 baseUrl은 /을 설정해주어야 합니다. url과 같이 사용되는 항목입니다. Always has both leading and trailing slash.

docusaurus.config.js
module.exports = {
baseUrl: '/',
};

선택 입력 항목

favicon

  • Type: string | undefined

Path to your site favicon; must be a URL that can be used in link's href. For example, if your favicon is in static/img/favicon.ico:

docusaurus.config.js
module.exports = {
favicon: '/img/favicon.ico',
};

trailingSlash

  • Type: boolean | undefined

URL/링크 끝 부분에 트레일링 슬래시 사용 여부와 정적 HTML 파일 생성 방식을 정의합니다.

  • undefined (default): URL을 그대로 유지하고 합니다. /docs/myDoc.md 파일은 /docs/myDoc/index.html파일로 생성됩니다.
  • true: URL/링크에 트레일링 슬래시를 추가합니다. /docs/myDoc.md 파일은 /docs/myDoc/index.html파일로 생성됩니다.
  • false: URL/링크에서 트레일링 슬래시를 제거합니다. /docs/myDoc.md 파일은 /docs/myDoc.html파일로 생성됩니다.
tip

Each static hosting provider serves static files differently (this behavior may even change over time).

적절한 설정 방법을 선택하기 위해 배포 가이드slorber/trailing-slash-guide를 참고하세요.

i18n

  • Type: Object

i18n 설정 오브젝트는 사이트 지역화를 위한 설정입니다.

예:

docusaurus.config.js
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fa'],
localeConfigs: {
en: {
label: 'English',
direction: 'ltr',
htmlLang: 'en-US',
calendar: 'gregory',
},
fa: {
label: 'فارسی',
direction: 'rtl',
htmlLang: 'fa-IR',
calendar: 'persian',
},
},
},
};
  • defaultLocale: The locale that (1) does not have its name in the base URL (2) gets started with docusaurus start without --locale option (3) will be used for the <link hrefLang="x-default"> tag
  • locales: List of locales deployed on your site. Must contain defaultLocale.
  • localeConfigs: Individual options for each locale.
    • label: The label displayed for this locale in the locales dropdown.
    • direction: ltr (default) or rtl (for right-to-left languages like Farsi, Arabic, Hebrew, etc.). Used to select the locale's CSS and html meta attribute.
    • htmlLang: <html lang="..."><link ... hreflang="...">에서 사용하는 BCP 47 language 태그
    • calendar: the calendar used to calculate the date era. Note that it doesn't control the actual string displayed: MM/DD/YYYY and DD/MM/YYYY are both gregory. To choose the format (DD/MM/YYYY or MM/DD/YYYY), set your locale name to en-GB or en-US (en means en-US).

noIndex

  • Type: boolean

This option adds <meta name="robots" content="noindex, nofollow"> to every page to tell search engines to avoid indexing your site (more information here).

예:

docusaurus.config.js
module.exports = {
noIndex: true, // Defaults to `false`
};
  • Type: 'ignore' | 'log' | 'warn' | 'error' | 'throw'

The behavior of Docusaurus when it detects any broken link.

기본적으로 깨진 링크가 배포되지 않도록 에러로 처리하지만 필요에 따라 수준을 조정할 수 있습니다.

note

링크의 깨짐 여부는 제품 빌드 시에만 확인할 수 있습니다 (docusaurus build).

  • Type: 'ignore' | 'log' | 'warn' | 'error' | 'throw'

The behavior of Docusaurus when it detects any broken markdown link.

기본적으로 깨진 마크다운 링크가 확인할 수 있도록 경고를 출력하지만 필요에 따라 수준을 조정할 수 있습니다.

onDuplicateRoutes

  • Type: 'ignore' | 'log' | 'warn' | 'error' | 'throw'

경로 중복을 발견했을 때 도큐사우루스에서 어떻게 처리할지 설정합니다.

기본적으로 yarn start 또는 yarn build 명령 실행 후에 경고를 출력합니다.

tagline

  • Type: string

웹 사이트를 설명하는 짧은 문구를 설정합니다.

docusaurus.config.js
module.exports = {
tagline:
'Docusaurus makes it easy to maintain Open Source documentation websites.',
};

organizationName

  • Type: string

코드 저장소를 소유하고 있는 깃허브 사용자 또는 그룹 계정을 설정합니다. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
module.exports = {
// Docusaurus' organization is facebook
organizationName: 'facebook',
};

projectName

  • Type: string

깃허브 저장소 이름을 설정합니다. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
module.exports = {
projectName: 'docusaurus',
};

deploymentBranch

  • Type: string

정적 파일을 배포할 브랜치 이름입니다. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
module.exports = {
deploymentBranch: 'gh-pages',
};

githubHost

  • Type: string

여러분의 서버 호스트 이름을 설정합니다. 깃허브 엔터프라이즈를 사용하는 경우 필요한 항목입니다. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
module.exports = {
githubHost: 'github.com',
};

githubPort

  • Type: string

여러분의 서버에서 사용하는 포트를 설정합니다. 깃허브 엔터프라이즈를 사용하는 경우 필요한 항목입니다. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
module.exports = {
githubPort: '22',
};

themeConfig

  • Type: Object

The theme configuration object to customize your site UI like navbar and footer.

예:

docusaurus.config.js
module.exports = {
themeConfig: {
docs: {
sidebar: {
hideable: false,
autoCollapseCategories: false,
},
},
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: true,
},
navbar: {
title: 'Site Title',
logo: {
alt: 'Site Logo',
src: 'img/logo.svg',
width: 32,
height: 32,
},
items: [
{
to: 'docs/docusaurus.config.js',
activeBasePath: 'docs',
label: 'docusaurus.config.js',
position: 'left',
},
// ... other links
],
},
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Docs',
to: 'docs/doc1',
},
],
},
// ... other links
],
logo: {
alt: 'Facebook Open Source Logo',
src: 'https://docusaurus.io/img/oss_logo.png',
width: 160,
height: 51,
},
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here
},
},
};

plugins

  • Type: PluginConfig[]
type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];

See plugin method references for the shape of a PluginModule.

docusaurus.config.js
module.exports = {
plugins: [
'docusaurus-plugin-awesome',
['docusuarus-plugin-confetti', {fancy: false}],
() => ({
postBuild() {
console.log('Build finished');
},
}),
],
};

themes

  • Type: PluginConfig[]
docusaurus.config.js
module.exports = {
themes: ['@docusaurus/theme-classic'],
};

presets

  • Type: PresetConfig[]
type PresetConfig = string | [string, any];
docusaurus.config.js
module.exports = {
presets: [],
};

customFields

도큐사우루스는 docusaurus.config.js 파일 내에 알 수 없는 필드가 추가되지 않도록 보호합니다. 사용자 지정 필드를 추가하고 싶다면 customFields에 설정해주어야 합니다.

  • Type: Object
docusaurus.config.js
module.exports = {
customFields: {
admin: 'endi',
superman: 'lol',
},
};

Attempting to add unknown fields in the config will lead to errors during build time:

Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js

staticDirectories

사이트 디렉토리 또는 절대 경로를 기준으로 한 경로 배열입니다. 해당 경로 아래의 파일은 있는 그대로 빌드 결과물로 복사됩니다.

  • Type: string[]

예:

docusaurus.config.js
module.exports = {
staticDirectories: ['static'],
};

scripts

로드할 스크립트 배열을 설정합니다. 값은 문자열이거나 속성, 값 조합으로 구성된 오브젝트일 수 있습니다. <script> 태그는 HTML <head> 태그 안에 추가됩니다.

Note that <script> added here are render-blocking, so you might want to add async: true/defer: true to the objects.

  • Type: (string | Object)[]

예:

docusaurus.config.js
module.exports = {
scripts: [
// String format.
'https://docusaurus.io/script.js',
// Object format.
{
src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
async: true,
},
],
};

stylesheets

로드할 CSS 소스의 배열을 설정합니다. 값은 문자열이거나 속성, 값 조합으로 구성된 오브젝트일 수 있습니다. <link> 태그는 HTML <head> 태그 안에 추가됩니다.

  • Type: (string | Object)[]

예:

docusaurus.config.js
module.exports = {
stylesheets: [
// String format.
'https://docusaurus.io/style.css',
// Object format.
{
href: 'http://mydomain.com/style.css',
},
],
};

clientModules

An array of client modules to load globally on your site.

예:

docusaurus.config.js
module.exports = {
clientModules: [
require.resolve('./mySiteGlobalJs.js'),
require.resolve('./mySiteGlobalCss.css'),
],
};

ssrTemplate

애플리케이션 렌더링 시 사용할 수 있는 Eta 구문으로 작성된 HTML 템플릿입니다. body 태그나 추가적인 meta 태그를 설정하거나 viewport를 설정하기 위해 사용할 수 있습니다. Please note that Docusaurus will rely on the template to be correctly structured in order to function properly, once you do customize it, you will have to make sure that your template is compliant with the requirements from upstream.

  • Type: string

예:

docusaurus.config.js
module.exports = {
ssrTemplate: `<!DOCTYPE html>
<html <%~ it.htmlAttributes %>>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Docusaurus v<%= it.version %>">
<% if (it.noIndex) { %>
<meta name="robots" content="noindex, nofollow" />
<% } %>
<%~ it.headTags %>
<% it.metaAttributes.forEach((metaAttribute) => { %>
<%~ metaAttribute %>
<% }); %>
<% it.stylesheets.forEach((stylesheet) => { %>
<link rel="stylesheet" href="<%= it.baseUrl %><%= stylesheet %>" />
<% }); %>
<% it.scripts.forEach((script) => { %>
<link rel="preload" href="<%= it.baseUrl %><%= script %>" as="script">
<% }); %>
</head>
<body <%~ it.bodyAttributes %>>
<%~ it.preBodyTags %>
<div id="__docusaurus">
<%~ it.appHtml %>
</div>
<% it.scripts.forEach((script) => { %>
<script src="<%= it.baseUrl %><%= script %>"></script>
<% }); %>
<%~ it.postBodyTags %>
</body>
</html>`,
};

titleDelimiter

  • Type: string

Will be used as title delimiter in the generated <title> tag.

예:

docusaurus.config.js
module.exports = {
titleDelimiter: '🦖', // Defaults to `|`
};

baseUrlIssueBanner

  • Type: boolean

활성화 시 사이트에서 CSS 또는 자바스크립트 파일을 로드하지 못하면 배너를 표시합니다. 이런 문제는 사이트 설정 시 잘못된 baseUrl로 인해 자주 발생할 수 있습니다.

예:

docusaurus.config.js
module.exports = {
baseUrlIssueBanner: true, // Defaults to `true`
};

baseUrlIssueBanner

caution

This banner needs to inline CSS / JS in case all asset loading fails due to wrong base URL.

엄격한 콘텐츠 보안 정책을 가지고 있다면 해당 기능을 활성화하지 마세요.