跳到主要内容

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

Title for your website. Will be used in metadata and as browser tab title.

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. Can be considered as 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. Always has both leading and trailing slash.

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

Optional fields

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

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
提示

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', '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 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.
  • path: Root folder which all locale folders are relative to. Can be absolute or relative to the config file. Defaults to i18n.
  • 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: 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 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).
    • path: Root folder that all plugin localization folders of this locale are relative to. Will be resolved against i18n.path. Defaults to the locale's name. Note: this has no effect on the locale's baseUrl—customization of base URL is a work-in-progress.

noIndex

  • 类型:boolean

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

示例:

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

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

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

:::注意

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

:::

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

当 Docusaurus 检测到任何 Markdown 死链时,Docusaurus 应该采取的行为。

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

onDuplicateRoutes

  • 类型: 'ignore' | 'log' | 'warn' | '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 用户或组织。如果你不使用 docusaurus deploy 命令部署网站的话,则不需要设置此参数。

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

projectName

  • 类型: string

GitHub 源码仓库的名称。如果你不使用 docusaurus deploy 命令部署网站的话,则不需要设置此参数。

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

deploymentBranch

  • Type: string

The name of the branch to deploy the static files to. You don't need this if you are not using the docusaurus deploy command.

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

githubHost

  • 类型:string

GitHub 服务器的主机名。如果你使用的是 GitHub 企业版,则会用到此参数。如果你不使用 docusaurus deploy 命令部署网站的话,则不需要设置此参数。

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

githubPort

  • Type: string

The port of your server. Useful if you are using GitHub Enterprise. You don't need this if you are not using the docusaurus deploy command.

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

themeConfig

  • 类型: Object

主题配置 对象可以用来自定义网站的 UI,例如导航条(navbar)和页脚(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: '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.

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'],
};

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; }[]

Example:

docusaurus.config.js
module.exports = {
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

An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. 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).

请注意,此处添加的 <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,
},
],
};

stylesheets

An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. 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)[]

Example:

docusaurus.config.js
module.exports = {
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.

示例:

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

ssrTemplate

Eta 语法 语法编写的 HTML 模板,用于渲染你的网站。该模板可以用来为 body 标签设置自定义的属性、添加额外的 meta 标签、自定义 viewport 等。请注意,Docusaurus 依赖此文件的正确结构才能正常运行,因此,一旦你修改了此文件,就必须确保你修改的模板符合 Docusaurus 的要求。

  • 类型:string

示例:

docusaurus.config.js
module.exports = {
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

  • 类型: string

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

示例:

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

baseUrlIssueBanner

  • 类型: boolean

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

示例:

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

A sample base URL issue banner. The style is very raw since the stylesheets failed to load. The text says &quot;Your Docusaurus site did not load properly... Current configured baseUrl = / (default value); We suggest trying baseUrl = /build/

警告

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

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