Version: 2.0.0-beta.21 🚧

`docusaurus.config.js`

概览

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

通常导出站点配置对象：

docusaurus.config.js
module.exports = {
  // site config...
};

配置文件也支持配置创建器函数和异步代码。

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

必填字段

`title`

类型：string

网站标题。 Will be used in metadata and as browser tab title.

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

您站点的相对路径。 Can be considered as the path after the host. For example, /metro/ is the base URL of https://facebook.github.io/metro/. 对于没有路径的网址，baseUrl 应设置为 /。此字段与 url 字段相对。 Always has both leading and trailing slash.

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

可选字段

`favicon`

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

类型：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: 'en',
    locales: ['en', 'fa'],
    localeConfigs: {
      en: {
        label: 'English',
        direction: 'ltr',
        htmlLang: 'en-US',
        calendar: 'gregory',
      },
      fa: {
        label: 'فارسی',
        direction: 'rtl',
        htmlLang: 'fa-IR',
        calendar: 'persian',
      },
    },
  },
};

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.
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="..."> 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).

`noIndex`

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

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

The behavior of Docusaurus when it detects any broken link.

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

note

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

`onBrokenMarkdownLinks`

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

The behavior of Docusaurus when it detects any broken markdown link.

默认情况下，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 用户或组织。 You don't need this if you are not using the docusaurus deploy command.

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

`projectName`

类型：string

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

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

`deploymentBranch`

类型：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 Enterprise。 You don't need this if you are not using the docusaurus deploy command.

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

`githubPort`

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

类型：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: '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 存在未知字段。 To add a custom field, define it on 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[]

示例：

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

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

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

`titleDelimiter`

类型：string

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 needs to inline CSS / JS in case all asset loading fails due to wrong base URL.

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

docusaurus.config.js

概览​

必填字段​

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​

stylesheets​

clientModules​

ssrTemplate​

titleDelimiter​

baseUrlIssueBanner​

caution

`docusaurus.config.js`

概览

必填字段

`title`

`url`

`baseUrl`

可选字段

`favicon`

`trailingSlash`

`i18n`

`noIndex`

`onBrokenLinks`

`onBrokenMarkdownLinks`

`onDuplicateRoutes`

`tagline`

`organizationName`

`projectName`

`deploymentBranch`

`githubHost`

`githubPort`

`themeConfig`

`plugins`

`themes`

`presets`

`customFields`

`staticDirectories`

`scripts`

`stylesheets`

`clientModules`

`ssrTemplate`

`titleDelimiter`

`baseUrlIssueBanner`