docusaurus.config.js
Overview
docusaurus.config.js
contains configurations for your site and is placed in the root directory of your site.
它通常会导出一个站点配置对象:
module.exports = {
// site config...
};
Config files also support config creator functions and async code.
module.exports = function configCreator() {
return {
// site config...
};
};
module.exports = async function configCreatorAsync() {
return {
// site config...
};
};
module.exports = Promise.resolve({
// site config...
});
Required fields
title
- Type:
string
网站标题。 会用于页面元数据中,以及浏览器选项卡标题。
module.exports = {
title: 'Docusaurus',
};
url
- Type:
string
网站网址。 你可以把它看作是顶级主机名。 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.
module.exports = {
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. 开头和末尾始终要包含斜杠。
module.exports = {
baseUrl: '/',
};
Optional fields
favicon
- Type:
string | undefined
你的网站图标的路径;必须是可以用于链接 href 的 URL。 For example, if your favicon is in static/img/favicon.ico
:
module.exports = {
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.
示例:
module.exports = {
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.
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).
示例:
module.exports = {
noIndex: true, // 默认为 `false`
};
onBrokenLinks
- Type:
'ignore' | 'log' | 'warn' | 'throw'
Docusaurus 在检测到无效链接时的行为。
默认情况下,Docusaurus 会抛出错误,保证你发布的网站不会包括任何无效链接,但你可以按需调整。
The broken links detection is only available for a production build (docusaurus build
).
onBrokenMarkdownLinks
- Type:
'ignore' | 'log' | 'warn' | 'throw'
Docusaurus 在检测到无效 Markdown 链接时的行为。
默认情况下,Docusaurus 会输出警告,告知你存在无效链接,但你可以按需调整。
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
网站标语。
module.exports = {
tagline:
'Docusaurus 让开源文档网站变得易于维护。',
};
organizationName
- Type:
string
拥有这个仓库的 GitHub 用户或组织。 You don't need this if you are not using the docusaurus deploy
command.
module.exports = {
// Docusaurus 的所属组织是 Facebook
organizationName: 'facebook',
};
projectName
- Type:
string
GitHub 仓库的名称。 You don't need this if you are not using the docusaurus deploy
command.
module.exports = {
projectName: 'docusaurus',
};
deploymentBranch
- Type:
string
要把静态文件部署到的分支名称。 You don't need this if you are not using the docusaurus deploy
command.
module.exports = {
deploymentBranch: 'gh-pages',
};
githubHost
- Type:
string
GitHub 服务器的主机名。 适用于 GitHub Enterprise。 You don't need this if you are not using the docusaurus deploy
command.
module.exports = {
githubHost: 'github.com',
};
githubPort
- Type:
string
服务器端口。 适用于 GitHub Enterprise。 You don't need this if you are not using the docusaurus deploy
command.
module.exports = {
githubPort: '22',
};
themeConfig
- Type:
Object
The theme configuration object to customize your site UI like navbar and footer.
示例:
module.exports = {
themeConfig: {
docs: {
sidebar: {
hideable: false,
autoCollapseCategories: false,
},
},
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: true,
},
navbar: {
title: '网站标题',
logo: {
alt: '网站图标',
src: 'img/logo.svg',
width: 32,
height: 32,
},
items: [
{
to: 'docs/docusaurus.config.js',
activeBasePath: 'docs',
label: 'docusaurus.config.js',
position: 'left',
},
// ……其他链接
],
},
footer: {
style: 'dark',
links: [
{
title: '文档',
items: [
{
label: '文档',
to: 'docs/doc1',
},
],
},
// ……其他链接
],
logo: {
alt: 'Meta 开源图标',
src: 'img/meta_oss_logo.png',
width: 160,
height: 51,
},
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // 你也可以在这里 写自定义的 HTML
},
},
};
plugins
- Type:
PluginConfig[]
type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];
See plugin method references for the shape of a PluginModule
.
module.exports = {
plugins: [
'docusaurus-plugin-awesome',
['docusuarus-plugin-confetti', {fancy: false}],
() => ({
postBuild() {
console.log('Build finished');
},
}),
],
};
themes
- Type:
PluginConfig[]
module.exports = {
themes: ['@docusaurus/theme-classic'],
};
presets
- Type:
PresetConfig[]
type PresetConfig = string | [string, any];
module.exports = {
presets: [],
};