版本：2.4.3

`docusaurus.config.js`

Overview

docusaurus.config.js contains configurations for your site and is placed in the root directory of your site.

它通常会导出一个站点配置对象：

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`

Type: string

网站标题。会用于页面元数据中，以及浏览器选项卡标题。

docusaurus.config.js
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.

docusaurus.config.js
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. 开头和末尾始终要包含斜杠。

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

Optional fields

`favicon`

Type: string | undefined

你的网站图标的路径；必须是可以用于链接 href 的 URL。 For example, if your favicon is in static/img/favicon.ico:

docusaurus.config.js
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.

示例：

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. 路径可以是绝对的，或者相对于配置文件。 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.). 用于选择语言的 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 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. 默认为语言的名称。 Note: this has no effect on the locale's baseUrl—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).

示例：

docusaurus.config.js
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

网站标语。

docusaurus.config.js
module.exports = {
  tagline:
    'Docusaurus 让开源文档网站变得易于维护。',
};

`organizationName`

Type: string

拥有这个仓库的 GitHub 用户或组织。 You don't need this if you are not using the docusaurus deploy command.

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

`projectName`

Type: string

GitHub 仓库的名称。 You don't need this if you are not using the docusaurus deploy command.

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

`deploymentBranch`

Type: string

要把静态文件部署到的分支名称。 You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
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.

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

`githubPort`

Type: string

服务器端口。适用于 GitHub Enterprise。 You don't need this if you are not using the docusaurus deploy command.

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

`themeConfig`

Type: Object

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

示例：

docusaurus.config.js
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.

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 guards docusaurus.config.js from unknown fields. To add a custom field, define it on customFields.

Type: Object

docusaurus.config.js
module.exports = {
  customFields: {
    admin: 'endi',
    superman: 'lol',
  },
};

试图在配置中添加未知字段会导致构建时错误：

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

示例：

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

示例：

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`

一组要加载的脚本。每个值可以是字符串，或是属性到值的对象映射表。 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)[]

示例：

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`

一组要加载的 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)[]

示例：

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`

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. 请注意，Docusaurus 需要此模板的结构完全正确才能正常工作。修改之后，你需要确保你的模板与上游的要求一致。

Type: 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`

Type: string

Will be used as title delimiter in the generated <title> tag.

示例：

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

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

示例：

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

A sample base URL issue banner. 样式非常粗糙，因为样式表加载失败了。 The text says "Your Docusaurus site did not load properly... Current configured baseUrl = / (default value); We suggest trying baseUrl = /build/

注意

这个横幅需要内联 CSS / JS，以防所有资源都因错误的 base URL 而加载失败。

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

docusaurus.config.js

Overview​

Required fields​

title​

url​

baseUrl​

Optional fields​

favicon​

trailingSlash​

i18n​

noIndex​

onBrokenLinks​

onBrokenMarkdownLinks​

onDuplicateRoutes​

tagline​

organizationName​

projectName​

deploymentBranch​

githubHost​

githubPort​

themeConfig​

plugins​

themes​

presets​

customFields​

staticDirectories​

headTags​

scripts​

stylesheets​

clientModules​

ssrTemplate​

titleDelimiter​

baseUrlIssueBanner​