跳到主要内容

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...
});

Required fields

title

  • 类型: string

网站的标题。

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

url

  • 类型: string

URL for your website. This can also be considered the top-level hostname. 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.

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

baseUrl

  • Type: string

Base URL for your site. This can also be considered the path after the host. 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.

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

Optional fields

favicon

  • Type: string | undefined

Path to your site favicon. For example, if your favicon is in static/img/favicon.ico:

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

trailingSlash

  • Type: boolean | undefined

Allow to customize the presence/absence of a trailing slash at the end of URLs/links, and how static HTML files are generated:

  • 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
tip

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

Refer to the deployment guide and slorber/trailing-slash-guide to choose the appropriate setting.

i18n

  • 类型:Object

i18n 参数用于配置 网站的本地化设置

示例:

docusaurus.config.js
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
localeConfigs: {
en: {
label: 'English',
direction: 'ltr',
htmlLang: 'en-US',
},
fr: {
label: 'Français',
direction: 'ltr',
htmlLang: 'fr-FR',
},
},
},
};
  • label: the label to use for this locale
  • direction: ltr (default) or rtl (for right-to-left languages like Arabic, Hebrew, etc.)
  • htmlLang: BCP 47 language tag to use in <html lang="..."> and in <link ... hreflang="...">

noIndex

  • 类型:boolean

如果开启此参数,Docusaurus 将在页面中添加 <meta name="robots" content="noindex, nofollow">,以告知搜索引擎不要索引你的网站(更多信息请参考 此处)。

示例:

docusaurus.config.js
module.exports = {
noIndex: true, // 默认值为 `false`
};
  • 类型: 'ignore' | 'log' | 'warn' | 'error' | 'throw'

当 Docusaurus 检测到任何无效的链接时所应采取的行为。

默认情况下,Docusaurus 会抛出错误,以确保你的网站永远不会包含任何无效的链接地址,但是如果需要的话也可以降低此安全等级。

:::注意

只在针对生产环境的构建时(即 docusaurus build)才检测无效链接。

:::

  • 类型: 'ignore' | 'log' | 'warn' | 'error' | 'throw'

当 Docusaurus 检测到任何无效的 markdown 链接时,Docusaurus 应该采取的行为。

默认情况下,Docusaurus 会输出警告信息,以便让你知到那些 markdown 链接是无效的,但是你可以根据需要更改此参数。

onDuplicateRoutes

  • 类型: 'ignore' | 'log' | 'warn' | 'error' | 'throw'

当 Docusaurus 检测到任何 重复路由 时所应采取的行为。

默认情况下,Docusaurus 会在执行 yarn startyarn build 之后显示警告信息。

tagline

  • 类型: string

网站的标语(tagline)。

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

organizationName

  • 类型: string

拥有此源码仓库的 GitHub 用户或组织。部署命令(deployment command)会用到此参数。

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

projectName

  • 类型: string

GitHub 源码仓库的名称。部署命令(deployment command)会用到此参数。

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

deploymentBranch

  • Type: string

The name of the branch to deploy the static files to. Used by the deployment command.

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

githubHost

  • 类型:string

GitHub 服务器的主机名。如果你使用的是 GitHub 企业版,则会用到此参数。.

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

githubPort

  • Type: string

The port of your server. Useful if you are using GitHub Enterprise.

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

themeConfig

  • 类型: Object

主题配置 对象可以用来自定义网站的 UI,例如导航条(navbar)和页脚(footer)。

例如:

docusaurus.config.js
module.exports = {
themeConfig: {
hideableSidebar: false,
autoCollapseSidebarCategories: 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 不允许在 docusaurus.config.js 配置文件中出现未知字段。如需添加自定义字段,请在 customFields 字段中进行配置。

  • 类型: 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

An array of paths, relative to the site's directory or absolute. Files under these paths will be copied to the build output as-is.

  • Type: string[]

Example:

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

scripts

此数组保存需要加载的脚本列表。此字段的值可以是字符串数组或键值对组成的普通对象(plain object)。所有 <script> 标签将被插入到 HTML <head> 标签中。

请注意,此处添加的 <script> 标签都会中断浏览器的渲染流程(render-blocking)的,因此你可能需要添加 async: true/defer: true

  • 类型:(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,
},
],
};

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 等。请注意,Docusaurus 依赖此文件的正确结构才能正常运行,因此,一旦你自定义了此文件,就必须确保你所自定义的模板符合上游(upstream)的要求。

  • 类型: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>`,
};

stylesheets

需要加载的 CSS 资源的列表。此字段的值可以是字符串数组或键值对组成的普通对象(plain object)。所有 <link> 标签都将被插入到 HTML <head> 标签中。

  • 类型: (string | Object)[]

例如:

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

titleDelimiter

  • 类型: string

该字符串将被用在生成的 <title> 标签中作为标题的分隔符使用。

示例:

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

baseUrlIssueBanner

  • 类型: boolean

开启此参数后,如果你的网站无法加载 CSS 或 JavaScript 文件,则会在页面顶部显示一条横幅来通知此问题。这一问题经常出现,通常与错误配置的 baseUrl 有关。

示例:

docusaurus.config.js
module.exports = {
baseUrlIssueBanner: true, // 默认值为 `true`
};

baseUrlIssueBanner

caution

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

如果你设置了严格的 内容安全策略,则需要禁止此参数。