跳转至主内容
Version: 2.0.0-beta.3

docusaurus.config.js

概览#

docusaurus.config.js 包含了您站点的配置信息，位于您网站的根目录。

必填字段#

title#

  • 类型：string

网站标题。

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

url#

  • 类型：string

网站网址。 您可将其视为顶级主机名。 举个例子，https://facebook.github.io 为https://facebook.github.io/metro/ 的顶级主机名，而 https://docusaurus.io 的顶级主机名则是其本身。 此字段与 baseUrl 字段相对。

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

baseUrl#

  • 类型：string

您站点的相对路径。 您可将其视为是主机名后的路径。 举个例子，/metro/ 为 https://facebook.github.io/metro/ 的 baseUrl。 对于没有路径的网址，baseUrl 应设置为 /。 此字段与 url 字段相对。

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

可选字段#

favicon#

  • 类型：string | undefined

网站图标路径

例如：如果你的图标位于 static/img/favicon.ico：

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

trailingSlash#

  • 类型：boolean | undefined

此选项允许您自定义 URL/链接后是否添加结尾斜杠。

  • undefined（默认）：不更改 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

每家静态托管托管商的处理方式均有所不同（而且甚至可能会随时间变化）。

请参阅部署指南及 slorber/trailing-slash-guide 来选择合适的设置。

i18n#

  • 类型：Object

用于本地化站点的 i18n 配置对象。

示例：

docusaurus.config.js
module.exports = {  i18n: {    defaultLocale: 'zh-cn',    locales: ['en', 'zh-cn'],    localeConfigs: {      en: {        label: 'English',        direction: 'ltr',      },      zh-cn: {        label: '中文（中国）',        direction: 'ltr',      },    },  },};
  • label：语言标签。
  • direction：ltr（默认）或 rtl（如阿拉伯语和希伯来语等的从右到左语言）。

noIndex#

  • 类型：boolean

此选项将在页面上添加 <meta name="robots" content="noindex, nofollow"> 以告知搜索引擎不要索引您的站点（详情参见此处）。

示例：

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

onBrokenLinks#

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

Docusaurus 在检测到无效链接时的行为。

默认情况下，Docusaurus 将抛出错误以保证您不会发布任何无效链接，但您可按需调整。

note

此选项仅限生产构建使用（docusaurus build）。

onBrokenMarkdownLinks#

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

Docusaurus 在检测到无效 Markdown 链接时的行为。

默认情况下，Docusaurus 将输出警告以告知您存在无效链接，但您可按需调整。

onDuplicateRoutes#

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

Docusaurus 在检测到重复路径时的行为。

默认情况下，Docusaurus 将在您运行 yarn start 或 yarn build 后输出警告。

tagline#

  • 类型：string

网站标语。

docusaurus.config.js
module.exports = {  tagline:    'Docusaurus 使得开源文档网站得以轻松维护。',};

organizationName#

  • 类型：string

拥有此源的 GitHub 用户或组织。 用于部署命令。

docusaurus.config.js
module.exports = {  // Docusaurus 的所有组织是 Facebook  organizationName: 'facebook',};

projectName#

  • 类型：string

GitHub 源的名称。 用于部署命令。

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

githubHost#

  • 类型：string

GitHub 服务器的主机名。 适用于 GitHub Enterprise。

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

githubPort#

  • 类型：string

服务器端口。 适用于 GitHub Enterprise。

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

themeConfig#

  • 类型：Object

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

示例：

docusaurus.config.js
module.exports = {  themeConfig: {    hideableSidebar: false,    colorMode: {      defaultMode: 'light',      disableSwitch: false,      respectPrefersColorScheme: true,      switchConfig: {        darkIcon: '🌙',        lightIcon: '\u2600',        // React 内联样式对象        // 参见 https://zh-hans.reactjs.org/docs/dom-elements.html#style        darkIconStyle: {          marginLeft: '2px',        },        lightIconStyle: {          marginLeft: '1px',        },      },    },    navbar: {      title: '网站标题',      logo: {        alt: '网站图标',        src: 'img/logo.svg',      },      items: [        {          to: 'docs/docusaurus.config.js',          activeBasePath: 'docs',          label: 'docusaurus.config.js',          position: 'left',        },        // ... other links      ],    },    footer: {      style: 'dark',      links: [        {          title: '文档',          items: [            {              label: '文档',              to: 'docs/doc1',            },          ],        },        // ... 其他链接      ],      logo: {        alt: 'Facebook 开源图标',        src: 'https://docusaurus.io/img/oss_logo.png',      },      copyright: `版权所有 © ${new Date().getFullYear()} Facebook, Inc。`, // 您也可以在此处使用 HTML 内容    },  },};

plugins#

  • 类型：any[]
docusaurus.config.js
module.exports = {  plugins: [],};

themes#

  • 类型：any[]
docusaurus.config.js
module.exports = {  themes: [],};

presets#

  • 类型：any[]
docusaurus.config.js
module.exports = {  presets: [],};

customFields#

Docusaurus 不允许 docusaurus.config.js 存在未知字段。 To add a custom field, define it on customFields.

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

Attempting to add unknown field in the config will lead to error in build time:

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

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>.

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

  • 类型：（string | Object）[]

示例：

docusaurus.config.js
module.exports = {  scripts: [    // 字符串格式。    'https://docusaurus.io/script.js',    // 对象格式。    {      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'),  ],};

See also: getClientModules().

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. 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.

  • 类型：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=0.86, maximum-scale=3.0, minimum-scale=0.86">    <meta name="generator" content="Docusaurus v<%= it.version %>">    <%~ 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 %> itemscope="" itemtype="http://schema.org/Organization">    <%~ it.preBodyTags %>    <div id="__docusaurus">      <%~ it.appHtml %>    </div>    <div id="outside-docusaurus">      <span>自定义标记</span>    </div>    <% it.scripts.forEach((script) => { %>      <script src="<%= it.baseUrl %><%= script %>"></script>    <% }); %>    <%~ it.postBodyTags %>  </body></html>};

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>.

  • 类型：（string | Object）[]

示例：

docusaurus.config.js
module.exports = {  stylesheets: [    // 字符串格式。    'https://docusaurus.io/style.css',    // 对象格式。    {      href: 'http://mydomain.com/style.css',    },  ],};

titleDelimiter#

  • 类型：string

A string that will be used as title delimiter in the generated <title> tag.

示例：

docusaurus.config.js
module.exports = {  titleDelimiter: '🦖', // 默认为 `|`};

baseUrlIssueBanner#

  • 类型：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.

示例：

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

baseUrlIssueBanner

caution

This banner need to inline CSS / JS.

If you have a strict Content Security Policy, you should rather disable it.