docusaurus.config.js
Refer to the Getting Started Configuration for examples.
Overview
docusaurus.config.js
contains configurations for your site and is placed in the root directory of your site.
With a TypeScript Docusaurus codebase your config file may be called docusaurus.config.ts
. The syntax is broadly identical to the js
config file with the addition of types. You can see an example on the Docusaurus Website itself.
This file is run in Node.js and should export a site configuration object, or a function that creates it.
The docusaurus.config.js
file supports:
예시:
export default {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
export default async function createConfigAsync() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
}
Refer to Syntax to declare docusaurus.config.js
for a more exhaustive list of examples and explanations.
Required fields
title
- Type:
string
웹 사이트 타이틀을 설정합니다. 메타데이터와 브라우저 탭 타이틀로 사용됩니다.
export default {
title: 'Docusaurus',
};
url
- Type:
string
웹 사이트의 URL을 설정합니다. 이 설정은 최상위 호스트 이름으로 처리되기도 합니다. For example, https://facebook.github.io
is the URL of https://facebook.github.io/metro/, and https://docusaurus.io
is the URL for https://docusaurus.io. This field is related to the baseUrl
field.
export default {
url: 'https://docusaurus.io',
};
baseUrl
- Type:
string
사이트의 Base URL을 설정합니다. 호스트 다음에 오는 경로로 처리되기도 합니다. For example, /metro/
is the base URL of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to /
. This field is related to the url
field. 항상 선행, 후행 슬래시가 있어야 합니다.
export default {
baseUrl: '/',
};
Optional fields
favicon
- Type:
string | undefined
사이트 파비콘 경로입니다. 해당 링크의 href에서 사용할 수 있는 URL이어야 합니다. For example, if your favicon is in static/img/favicon.ico
:
export default {
favicon: '/img/favicon.ico',
};
trailingSlash
- Type:
boolean | undefined
URL/링크 끝 부분에 트레일링 슬래시 사용 여부와 정적 HTML 파일 생성 방식을 정의합니다.
undefined
(default): keeps URLs untouched, and emit/docs/myDoc/index.html
for/docs/myDoc.md
true
: add trailing slashes to URLs/links, and emit/docs/myDoc/index.html
for/docs/myDoc.md
false
: remove trailing slashes from URLs/links, and emit/docs/myDoc.html
for/docs/myDoc.md
정적 호스팅 제공 업체에 따라 정적 파일은 다른 방식으로 제공합니다(이 동작 또한 변경될 수 있습니다).
Refer to the deployment guide and slorber/trailing-slash-guide to choose the appropriate setting.
i18n
- Type:
Object
The i18n configuration object to localize your site.
예:
export default {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fa'],
path: 'i18n',
localeConfigs: {
en: {
label: 'English',
direction: 'ltr',
htmlLang: 'en-US',
calendar: 'gregory',
path: 'en',
},
fa: {
label: 'فارسی',
direction: 'rtl',
htmlLang: 'fa-IR',
calendar: 'persian',
path: 'fa',
},
},
},
};
defaultLocale
: The locale that (1) does not have its name in the base URL (2) gets started withdocusaurus start
without--locale
option (3) will be used for the<link hrefLang="x-default">
taglocales
: List of locales deployed on your site. Must containdefaultLocale
.path
: Root folder which all locale folders are relative to. 구성 파일에 따라 절대적이거나 상대적일 수 있습니다. Defaults toi18n
.localeConfigs
: Individual options for each locale.label
: The label displayed for this locale in the locales dropdown.direction
:ltr
(default) orrtl
(for right-to-left languages like Farsi, Arabic, Hebrew, etc.). 해당 로케일의 CSS, HTML 메타 속성을 선택할 때 사용합니다.htmlLang
: BCP 47 language tag to use in<html lang="...">
(or any other DOM tag name) and in<link ... hreflang="...">
calendar
: the calendar used to calculate the date era. Note that it doesn't control the actual string displayed:MM/DD/YYYY
andDD/MM/YYYY
are bothgregory
. To choose the format (DD/MM/YYYY
orMM/DD/YYYY
), set your locale name toen-GB
oren-US
(en
meansen-US
).path
: Root folder that all plugin localization folders of this locale are relative to. Will be resolved againsti18n.path
. 기본값은 로케일 이름입니다. Note: this has no effect on the locale'sbaseUrl
—customization of base URL is a work-in-progress.
future
- Type:
Object
The future
configuration object permits to opt-in for upcoming/unstable/experimental Docusaurus features that are not ready for prime time.
It is also a way to opt-in for upcoming breaking changes coming in the next major versions, enabling you to prepare your site for the next version while staying on the previous one. The Remix Future Flags blog post greatly explains this idea.
Features prefixed by experimental_
or unstable_
are subject to changes in minor versions, and not considered as Semantic Versioning breaking changes.
Features prefixed by v<MajorVersion>_
(v6_
v7_
, etc.) are future flags that are expected to be turned on by default in the next major versions. These are less likely to change, but we keep the possibility to do so.
future
API breaking changes should be easy to handle, and will be documented in minor/major version blog posts.
예:
export default {
future: {
experimental_storage: {
type: 'localStorage',
namespace: true,
},
experimental_router: 'hash',
},
};
experimental_storage
: Site-wide browser storage options that theme authors should strive to respect.type
: The browser storage theme authors should use. Possible values arelocalStorage
andsessionStorage
. Defaults tolocalStorage
.namespace
: Whether to namespace the browser storage keys to avoid storage key conflicts when Docusaurus sites are hosted under the same domain, or on localhost. Possible values arestring | boolean
. The namespace is appended at the end of the storage keyskey-namespace
. Usetrue
to automatically generate a random namespace from your siteurl + baseUrl
. Defaults tofalse
(no namespace, historical behavior).
experimental_router
: The router type to use. Possible values arebrowser
andhash
. Defaults tobrowser
. Thehash
router is only useful for rare cases where you want to opt-out of static site generation, have a fully client-side app with a singleindex.html
entrypoint file. This can be useful to distribute a Docusaurus site as a.zip
archive that you can browse locally without running a web server.
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).
예:
export default {
noIndex: true, // Defaults to `false`
};
onBrokenLinks
- Type:
'ignore' | 'log' | 'warn' | 'throw'
깨진 링크를 발견했을 때 도큐사우루스에서 어떻게 처리할지 설정합니다.
By default, it throws an error, to ensure you never ship any broken link.
The broken links detection is only available for a production build (docusaurus build
).
onBrokenAnchors
- Type:
'ignore' | 'log' | 'warn' | 'throw'
The behavior of Docusaurus when it detects any broken anchor declared with the Heading
component of Docusaurus.
By default, it prints a warning, to let you know about your broken anchors.
onBrokenMarkdownLinks
- Type:
'ignore' | 'log' | 'warn' | 'throw'
깨진 마크다운 링크를 발견했을 때 도큐사우루스에서 어떻게 처리할지 설정합니다.
By default, it prints a warning, to let you know about your broken Markdown link.
onDuplicateRoutes
- Type:
'ignore' | 'log' | 'warn' | 'throw'
The behavior of Docusaurus when it detects any duplicate routes.
By default, it displays a warning after you run yarn start
or yarn build
.
tagline
- Type:
string
웹 사이트를 설명하는 짧은 문구를 설정합니다.
export default {
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.
export default {
// Docusaurus' organization is facebook
organizationName: 'facebook',
};
projectName
- Type:
string
깃허브 저장소 이름을 설정합니다. You don't need this if you are not using the docusaurus deploy
command.
export default {
projectName: 'docusaurus',
};
deploymentBranch
- Type:
string
정적 파일을 배포할 브랜치 이름입니다. You don't need this if you are not using the docusaurus deploy
command.
export default {
deploymentBranch: 'gh-pages',
};
githubHost
- Type:
string
여러분의 서버 호스트 이름을 설정합니다. 깃허브 엔터프라이즈를 사용하는 경우 필요한 항목입니다. You don't need this if you are not using the docusaurus deploy
command.
export default {
githubHost: 'github.com',
};
githubPort
- Type:
string
여러분의 서버에서 사용하는 포트를 설정합니다. 깃허브 엔터프라이즈를 사용하는 경우 필요한 항목입니다. You don't need this if you are not using the docusaurus deploy
command.
export default {
githubPort: '22',
};
themeConfig
- Type:
Object
The theme configuration object to customize your site UI like navbar and footer.
예:
export default {
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: 'Meta Open Source Logo',
src: 'img/meta_oss_logo.png',
href: 'https://opensource.fb.com',
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
.
export default {
plugins: [
'docusaurus-plugin-awesome',
['docusuarus-plugin-confetti', {fancy: false}],
() => ({
postBuild() {
console.log('Build finished');
},
}),
],
};
themes
- Type:
PluginConfig[]
export default {
themes: ['@docusaurus/theme-classic'],
};
presets
- Type:
PresetConfig[]
type PresetConfig = string | [string, any];
export default {
presets: [],
};
markdown
전역 도큐사우루스 마크다운 설정입니다.
- Type:
MarkdownConfig
type MarkdownPreprocessor = (args: {
filePath: string;
fileContent: string;
}) => string;
type MDX1CompatOptions =
| boolean
| {
comments: boolean;
admonitions: boolean;
headingIds: boolean;
};
export type ParseFrontMatter = (params: {
filePath: string;
fileContent: string;
defaultParseFrontMatter: ParseFrontMatter;
}) => Promise<{
frontMatter: {[key: string]: unknown};
content: string;
}>;
type MarkdownAnchorsConfig = {
maintainCase: boolean;
};
type MarkdownConfig = {
format: 'mdx' | 'md' | 'detect';
mermaid: boolean;
preprocessor?: MarkdownPreprocessor;
parseFrontMatter?: ParseFrontMatter;
mdx1Compat: MDX1CompatOptions;
remarkRehypeOptions: object; // see https://github.com/remarkjs/remark-rehype#options
anchors: MarkdownAnchorsConfig;
};
예:
export default {
markdown: {
format: 'mdx',
mermaid: true,
preprocessor: ({filePath, fileContent}) => {
return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
},
parseFrontMatter: async (params) => {
const result = await params.defaultParseFrontMatter(params);
result.frontMatter.description =
result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
return result;
},
mdx1Compat: {
comments: true,
admonitions: true,
headingIds: true,
},
anchors: {
maintainCase: true,
},
},
};
옵션명 | 타입 | 기본값 | 설명 |
---|---|---|---|
format | 'mdx' | 'md' | 'detect' | 'mdx' | The default parser format to use for Markdown content. Using 'detect' will select the appropriate format automatically based on file extensions: .md vs .mdx . |
mermaid | boolean | false | When true , allows Docusaurus to render Markdown code blocks with mermaid language as Mermaid diagrams. |
preprocessor | MarkdownPreprocessor | undefined | Gives you the ability to alter the Markdown content string before parsing. Use it as a last-resort escape hatch or workaround: it is almost always better to implement a Remark/Rehype plugin. |
parseFrontMatter | ParseFrontMatter | undefined | Gives you the ability to provide your own front matter parser, or to enhance the default parser. Read our front matter guide for details. |
mdx1Compat | MDX1CompatOptions | {comments: true, admonitions: true, headingIds: true} | Compatibility options to make it easier to upgrade to Docusaurus v3+. |
anchors | MarkdownAnchorsConfig | {maintainCase: false} | Options to control the behavior of anchors generated from Markdown headings |
remarkRehypeOptions | object | undefined | Makes it possible to pass custom remark-rehype options. |
customFields
Docusaurus guards docusaurus.config.js
from unknown fields. To add a custom field, define it on customFields
.
- Type:
Object
export default {
customFields: {
admin: 'endi',
superman: 'lol',
},
};
알 수 없는 필드 항목을 설정 파일에 추가한 경우 빌드 시 아래와 같은 에러가 발생합니다.
Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js
staticDirectories
사이트 디렉토리 또는 절대 경로를 기준으로 한 경로 배열입니다. 해당 경로 아래의 파일은 있는 그대로 빌드 결과물로 복사됩니다.
- Type:
string[]
예:
export default {
staticDirectories: ['static'],
};
headTags
An array of tags that will be inserted in the HTML <head>
. The values must be objects that contain two properties; tagName
and attributes
. tagName
must be a string that determines the tag being created; eg "link"
. attributes
must be an attribute-value map.
- Type:
{ tagName: string; attributes: Object; }[]
예:
export default {
headTags: [
{
tagName: 'link',
attributes: {
rel: 'icon',
href: '/img/docusaurus.png',
},
},
],
};
This would become <link rel="icon" href="img/docusaurus.png" />
in the generated HTML.
scripts
로드할 스크립트 배열을 설정합니다. 값은 문자열이거나 속성, 값 조합으로 구성된 오브젝트일 수 있습니다. The <script>
tags will be inserted in the HTML <head>
. If you use a plain object, the only required attribute is src
, and any other attributes are permitted (each one should have boolean/string values).
Note that <script>
added here are render-blocking, so you might want to add async: true
/defer: true
to the objects.
- Type:
(string | Object)[]
예:
export default {
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 소스의 배열을 설정합니다. 값은 문자열이거나 속성, 값 조합으로 구성된 오브젝트일 수 있습니다. The <link>
tags will be inserted in the HTML <head>
. If you use an object, the only required attribute is href
, and any other attributes are permitted (each one should have boolean/string values).
- Type:
(string | Object)[]
예:
export default {
stylesheets: [
// String format.
'https://docusaurus.io/style.css',
// Object format.
{
href: 'http://mydomain.com/style.css',
},
],
};
By default, the <link>
tags will have rel="stylesheet"
, but you can explicitly add a custom rel
value to inject any kind of <link>
tag, not necessarily stylesheets.
clientModules
An array of client modules to load globally on your site.
예:
export default {
clientModules: ['./mySiteGlobalJs.js', './mySiteGlobalCss.css'],
};
ssrTemplate
An HTML template written in Eta's syntax that will be used to render your application. This can be used to set custom attributes on the body
tags, additional meta
tags, customize the viewport
, etc. 도큐사우루스는 올바르게 동작하기 위해 템플릿이 제대로 작성되었는지 확인합니다. 사용자 지정 템플릿을 작성한 경우에는 upstream 요구사항을 제대로 반영했는지 확인해주세요.
- Type:
string
예:
export default {
ssrTemplate: `<!DOCTYPE html>
<html <%~ it.htmlAttributes %>>
<head>
<meta charset="UTF-8">
<meta name="generator" content="Docusaurus v<%= it.version %>">
<% it.metaAttributes.forEach((metaAttribute) => { %>
<%~ metaAttribute %>
<% }); %>
<%~ it.headTags %>
<% 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.
예:
export default {
titleDelimiter: '🦖', // Defaults to `|`
};
baseUrlIssueBanner
- Type:
boolean
When enabled, will show a banner in case your site can't load its CSS or JavaScript files, which is a very common issue, often related to a wrong baseUrl
in site config.
예:
export default {
baseUrlIssueBanner: true, // Defaults to `true`
};
이 배너는 잘못된 base URL로 인하 모든 애셋 로드가 실패하는 경우 인라인 CSS / JS로 처리됩니다.
If you have a strict Content Security Policy, you should rather disable it.