Skip to main content
Version: 3.0.1

docusaurus.config.js


信息

有关示例，请参阅入门 配置。

英Refer to the Getting Started Configuration for examples.

概述​

docusaurus.config.js 包含你站点的配置，并放置在你站点的根目录中。

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

该文件在 Node.js 中运行，并应导出站点配置对象或创建它的函数。

英This file is run in Node.js and should export a site configuration object, or a function that creates it.

docusaurus.config.js 文件支持：

英The docusaurus.config.js file supports:

例子：

英Examples:

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.nodejs.cn',
  // your site config ...
};
docusaurus.config.js
export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.nodejs.cn',
    // your site config ...
  };
}
提示

请参阅 声明 docusaurus.config.js 的语法 以获取更详尽的示例和解释列表。

英Refer to Syntax to declare docusaurus.config.js for a more exhaustive list of examples and explanations.

必填字段​

title​

  • 类型： string

你网站的标题。 将在元数据中使用并用作浏览器选项卡标题。

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

docusaurus.config.js
export default {
  title: 'Docusaurus',
};

url​

  • 类型： string

你网站的 URL。 这也可以被视为顶层主机名。 例如，https://facebook.github.io 是 https://facebook.github.io/metro/ 的 URL，https://docusaurus.nodejs.cn 是 https://docusaurus.nodejs.cn 的 URL。 该字段与 baseUrl 字段相关。

英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.nodejs.cn is the URL for https://docusaurus.nodejs.cn. This field is related to the baseUrl field.

docusaurus.config.js
export default {
  url: 'https://docusaurus.nodejs.cn',
};

baseUrl​

  • 类型： string

你网站的基本 URL。 可以认为是宿主之后的路径。 例如，/metro/ 是 https://facebook.github.io/metro/ 的基本 URL。 对于没有路径的 URL，baseUrl 应设置为 /。 该字段与 url 字段相关。 始终有前导斜杠和尾随斜杠。

英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
export default {
  baseUrl: '/',
};

可选字段​

favicon​

  • 类型： string | undefined

你网站图标的路径； 必须是可在链接的 href 中使用的 URL。 例如，如果你的网站图标位于 static/img/favicon.ico：

英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
export default {
  favicon: '/img/favicon.ico',
};

trailingSlash​

  • 类型： boolean | undefined

允许自定义 URL/链接末尾是否存在尾部斜杠，以及如何生成静态 HTML 文件：

英Allow to customize the presence/absence of a trailing slash at the end of URLs/links, and how static HTML files are generated:

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

每个静态托管提供商以不同的方式提供静态文件（这种行为甚至可能随着时间的推移而改变）。

英Each static hosting provider serves static files differently (this behavior may even change over time).

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

英Refer to the deployment guide and slorber/trailing-slash-guide to choose the appropriate setting.

i18n​

  • 类型： Object

i18n 配置对象为 本地化你的网站。

英The i18n configuration object to localize your site.

例子：

英Example:

docusaurus.config.js
export default {
  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： (1) 基本 URL 中没有其名称的语言环境 (2) 以 docusaurus start 开头，没有 --locale 选项 (3) 将用于 <link hrefLang="x-default"> 标记
  • locales： 你站点上部署的区域设置列表。 必须包含 defaultLocale。
  • path： 所有语言环境文件夹都相对于的根文件夹。 可以是绝对的或相对于配置文件的。 默认为 i18n。
  • localeConfigs： 每个区域设置的单独选项。
    • label： 在区域设置下拉列表中为此区域设置显示的标签。
    • direction： ltr（默认）或 rtl（对于 从右到左的语言，如波斯语、阿拉伯语、希伯来语等）。 用于选择区域设置的 CSS 和 HTML 元属性。
    • htmlLang： 在 <html lang="...">（或任何其他 DOM 标签名称）和 <link ... hreflang="..."> 中使用的 BCP 47 语言标签
    • calendar： calendar 用于计算日期纪元。 请注意，它不控制实际显示的字符串： MM/DD/YYYY 和 DD/MM/YYYY 都是 gregory。 要选择格式（DD/MM/YYYY 或 MM/DD/YYYY），请将区域设置名称设置为 en-GB 或 en-US（en 表示 en-US）。
    • path： 该语言环境的所有插件本地化文件夹都相对于的根文件夹。 将针对 i18n.path 解决。 默认为区域设置的名称。 注意： 这对区域设置的 baseUrl 没有影响—基本 URL 的定制工作正在进行中。

noIndex​

  • 类型： boolean

此选项将 <meta name="robots" content="noindex, nofollow"> 添加到每个页面，以告诉搜索引擎避免对你的网站建立索引（更多信息 此处）。

英This option adds <meta name="robots" content="noindex, nofollow"> to every page to tell search engines to avoid indexing your site (more information here).

例子：

英Example:

docusaurus.config.js
export default {
  noIndex: true, // Defaults to `false`
};
  • 类型： 'ignore' | 'log' | 'warn' | 'throw'

Docusaurus 检测到任何损坏的链接时的行为。

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

默认情况下，它会抛出错误，以确保你永远不会发送任何损坏的链接，但如果需要，你可以降低此安全性。

英By default, it throws an error, to ensure you never ship any broken link, but you can lower this security if needed.

注意

损坏的链接检测仅适用于生产版本 (docusaurus build)。

英The broken links detection is only available for a production build (docusaurus build).

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

Docusaurus 检测到任何损坏的 Markdown 链接时的行为。

英The behavior of Docusaurus when it detects any broken Markdown link.

默认情况下，它会打印一条警告，让你知道损坏的 Markdown 链接，但你可以根据需要更改此安全性。

英By default, it prints a warning, to let you know about your broken Markdown link, but you can change this security if needed.

onDuplicateRoutes​

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

Docusaurus 检测到任何 重复路由 时的行为。

英The behavior of Docusaurus when it detects any duplicate routes.

默认情况下，运行 yarn start 或 yarn build 后会显示警告。

英By default, it displays a warning after you run yarn start or yarn build.

tagline​

  • 类型： string

你网站的标语。

英The tagline for your website.

docusaurus.config.js
export default {
  tagline:
    'Docusaurus makes it easy to maintain Open Source documentation websites.',
};

organizationName​

  • 类型： string

拥有存储库的 GitHub 用户或组织。 如果你不使用 docusaurus deploy 命令，则不需要此命令。

英The GitHub user or organization that owns the repository. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
export default {
  // Docusaurus' organization is facebook
  organizationName: 'facebook',
};

projectName​

  • 类型： string

GitHub 存储库的名称。 如果你不使用 docusaurus deploy 命令，则不需要此命令。

英The name of the GitHub repository. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
export default {
  projectName: 'docusaurus',
};

deploymentBranch​

  • 类型： string

将静态文件部署到的分支的名称。 如果你不使用 docusaurus deploy 命令，则不需要此命令。

英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
export default {
  deploymentBranch: 'gh-pages',
};

githubHost​

  • 类型： string

你的服务器的主机名。 如果你使用 GitHub Enterprise，则很有用。 如果你不使用 docusaurus deploy 命令，则不需要此命令。

英The hostname 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
export default {
  githubHost: 'github.com',
};

githubPort​

  • 类型： string

你的服务器的端口。 如果你使用 GitHub Enterprise，则很有用。 如果你不使用 docusaurus deploy 命令，则不需要此命令。

英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
export default {
  githubPort: '22',
};

themeConfig​

  • 类型： Object

主题配置 对象用于自定义站点 UI，如导航栏和页脚。

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

例子：

英Example:

docusaurus.config.js
export default {
  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​

  • 类型： PluginConfig[]
type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];

参见 插件方法参考 了解 PluginModule 的形状。

英See plugin method references for the shape of a PluginModule.

docusaurus.config.js
export default {
  plugins: [
    'docusaurus-plugin-awesome',
    ['docusuarus-plugin-confetti', {fancy: false}],
    () => ({
      postBuild() {
        console.log('Build finished');
      },
    }),
  ],
};

themes​

  • 类型： PluginConfig[]
docusaurus.config.js
export default {
  themes: ['@docusaurus/theme-classic'],
};

presets​

  • 类型： PresetConfig[]
type PresetConfig = string | [string, any];
docusaurus.config.js
export default {
  presets: [],
};

markdown​

全局 Docusaurus Markdown 配置。

英The global Docusaurus Markdown config.

  • 类型： MarkdownConfig
type MarkdownPreprocessor = (args: {
  filePath: string;
  fileContent: string;
}) => string;

type MDX1CompatOptions =
  | boolean
  | {
      comments: boolean;
      admonitions: boolean;
      headingIds: boolean;
    };

type MarkdownConfig = {
  format: 'mdx' | 'md' | 'detect';
  mermaid: boolean;
  preprocessor?: MarkdownPreprocessor;
  mdx1Compat: MDX1CompatOptions;
};

例子：

英Example:

docusaurus.config.js
export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};
名称类型默认描述
format'mdx' | 'md' | 'detect''mdx'用于 Markdown 内容的默认解析器格式。 使用 'detect' 将根据文件扩展名自动选择适当的格式： .md 与 .mdx。
mermaidbooleanfalsetrue 时，允许 Docusaurus 将 mermaid 语言的 Markdown 代码块渲染为 Mermaid 图表。
preprocessorMarkdownPreprocessorundefined使你能够在解析之前更改 Markdown 内容字符串。 将其用作最后的应急方案或解决方法： 实现 Remark/Rehype 插件几乎总是更好。
mdx1CompatMDX1CompatOptions{comments: true, admonitions: true, headingIds: true}兼容性选项可让你更轻松地升级到 Docusaurus v3+。

customFields​

Docusaurus 守护着来自未知字段的 docusaurus.config.js。 要添加自定义字段，请在 customFields 上定义它。

英Docusaurus guards docusaurus.config.js from unknown fields. To add a custom field, define it on customFields.

  • 类型： Object
docusaurus.config.js
export default {
  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.

  • 类型： string[]

例子：

英Example:

docusaurus.config.js
export default {
  staticDirectories: ['static'],
};

headTags​

将插入 HTML <head> 中的标签数组。 这些值必须是包含两个属性的对象； tagName 和 attributes。 tagName 必须是一个字符串，用于确定正在创建的标签； 例如 "link"。 attributes 必须是属性值映射。

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

  • 类型： { tagName: string; attributes: Object; }[]

例子：

英Example:

docusaurus.config.js
export default {
  headTags: [
    {
      tagName: 'link',
      attributes: {
        rel: 'icon',
        href: '/img/docusaurus.png',
      },
    },
  ],
};

这将在生成的 HTML 中变成 <link rel="icon" href="img/docusaurus.png" />。

英This would become <link rel="icon" href="img/docusaurus.png" /> in the generated HTML.

scripts​

要加载的脚本数组。 这些值可以是字符串或属性值映射的普通对象。 <script> 标签将插入 HTML <head> 中。 如果你使用普通对象，则唯一必需的属性是 src，并且允许任何其他属性（每个属性都应该具有布尔/字符串值）。

英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> 是渲染阻塞的，因此你可能需要将 async: true/defer: true 添加到对象中。

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

  • 类型： (string | Object)[]

例子：

英Example:

docusaurus.config.js
export default {
  scripts: [
    // String format.
    'https://docusaurus.nodejs.cn/script.js',
    // Object format.
    {
      src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
      async: true,
    },
  ],
};

stylesheets​

要加载的 CSS 源数组。 这些值可以是字符串或属性值映射的普通对象。 <link> 标签将插入 HTML <head> 中。 如果你使用对象，则唯一必需的属性是 href，并且允许任何其他属性（每个属性都应该具有布尔/字符串值）。

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

  • 类型： (string | Object)[]

例子：

英Example:

docusaurus.config.js
export default {
  stylesheets: [
    // String format.
    'https://docusaurus.nodejs.cn/style.css',
    // Object format.
    {
      href: 'http://mydomain.com/style.css',
    },
  ],
};
信息

默认情况下，<link> 标签将具有 rel="stylesheet"，但你可以显式添加自定义 rel 值来注入任何类型的 <link> 标签，不一定是样式表。

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

例子：

英Example:

docusaurus.config.js
export default {
  clientModules: ['./mySiteGlobalJs.js', './mySiteGlobalCss.css'],
};

ssrTemplate​

用 Eta 的语法 编写的 HTML 模板，将用于渲染你的应用。 这可用于在 body 标签、附加 meta 标签、自定义 viewport 等上设置自定义属性。请注意，Docusaurus 将依赖模板正确构建才能正常运行，一旦你对其进行自定义，你将 必须确保你的模板符合上游的要求。

英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

例子：

英Example:

docusaurus.config.js
export default {
  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> 标记中的标题分隔符。

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

例子：

英Example:

docusaurus.config.js
export default {
  titleDelimiter: '🦖', // Defaults to `|`
};

baseUrlIssueBanner​

  • 类型： boolean

启用后，将显示一个横幅，以防你的网站无法加载其 CSS 或 JavaScript 文件，这是一个非常常见的问题，通常与网站配置中的错误 baseUrl 有关。

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

例子：

英Example:

docusaurus.config.js
export default {
  baseUrlIssueBanner: true, // Defaults to `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/

警告

此横幅需要内联 CSS / JS，以防所有资源加载由于错误的基本 URL 而失败。

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