Version: 2.0.0-beta.10 🚧

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

`deploymentBranch`

类型：string

The name of the branch to deploy the static files to. 用于部署命令。

docusaurus.config.js

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

`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 inline style object
        // see https://reactjs.org/docs/dom-elements.html#style
        darkIconStyle: {
          marginLeft: '2px',
        },
        lightIconStyle: {
          marginLeft: '1px',
        },
      },
    },
    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`

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

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

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

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

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.

概览​

必填字段​

title​

url​

baseUrl​

可选字段​

favicon​

trailingSlash​

tip

i18n​

noIndex​

onBrokenLinks​

note

onBrokenMarkdownLinks​

onDuplicateRoutes​

tagline​

organizationName​

projectName​

deploymentBranch​

githubHost​

githubPort​

themeConfig​

plugins​

themes​

presets​

customFields​

staticDirectories​

scripts​

clientModules​

ssrTemplate​

stylesheets​

titleDelimiter​

baseUrlIssueBanner​

caution

概览

必填字段

`title`

`url`

`baseUrl`

可选字段

`favicon`

`trailingSlash`

`i18n`

`noIndex`

`onBrokenLinks`

`onBrokenMarkdownLinks`

`onDuplicateRoutes`

`tagline`

`organizationName`

`projectName`

`deploymentBranch`

`githubHost`

`githubPort`

`themeConfig`

`plugins`

`themes`

`presets`

`customFields`

`staticDirectories`

`scripts`

`clientModules`

`ssrTemplate`

`stylesheets`

`titleDelimiter`

`baseUrlIssueBanner`