`docusaurus.config.js`配置

信息

有关示例，请参阅“入门”中的配置。

概述

docusaurus.config.js 文件包含了网站的配置，它位于你网站的根目录中。

备注

如果你的道格龙（Docusaurus）代码库使用了 TypeScript，那么你的配置文件可能会被命名为 docusaurus.config.ts。其语法与 js 配置文件基本相同，只是增加了类型定义。你可以在道格龙（Docusaurus）官网上查看一个实际的例子。

此文件 在 Node.js 环境中运行，并且应当导出一个网站配置对象，或一个创建该对象的函数。

docusaurus.config.js 文件支持：

示例：

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // 你的站点配置...
};

docusaurus.config.js
export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // 你的站点配置...
  };
}

提示

关于更详尽的示例和解释，请参阅 声明 docusaurus.config.js 的语法。

必填字段

`title`

类型：string

你网站的标题。它将用于元数据（metadata）和浏览器标签页标题。

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

`url`

类型：string

你网站的 URL。这也可以被视作顶级域名。例如，https://facebook.github.io/metro/ 的 URL 是 https://facebook.github.io，而 https://docusaurus.io 的 URL 是 https://docusaurus.io。此字段与 baseUrl 字段相关。

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

`baseUrl`

类型：string

你网站的根路径（Base URL）。可以将其看作是域名后面的路径部分。例如，/metro/ 是 https://facebook.github.io/metro/ 的根路径。对于没有路径的 URL，baseUrl 应设置为 /。此字段与 url 字段相关。它应该总是在开头和结尾都带上斜杠。

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

可选字段

`favicon`

类型：string | undefined

你网站图标（favicon）的路径；必须是一个可以用于链接 href 属性的 URL。例如，如果你的图标位于 static/img/favicon.ico：

docusaurus.config.js
export default {
  favicon: '/img/favicon.ico',
};

`trailingSlash`

类型：boolean | undefined

允许自定义 URL/链接末尾是否带有斜杠，以及静态 HTML 文件的生成方式：

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

提示

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

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

`i18n`

类型：Object

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

示例：

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) 在不带 --locale 选项的情况下通过 docusaurus start 启动 (3) 将用于 <link hrefLang="x-default"> 标签。
locales：在你的网站上部署的语言环境列表。必须包含 defaultLocale。
path：所有语言环境文件夹的根目录，路径可以是绝对路径，也可以是相对于配置文件的相对路径。默认为 i18n。
localeConfigs：每个语言环境的单独选项。
- label：此语言环境在语言下拉菜单中显示的标签。
- direction：ltr (默认) 或 rtl (用于从右到左书写的语言，如波斯语、阿拉伯语、希伯来语等)。用于选择语言环境的 CSS 和 HTML meta 属性。
- htmlLang：用于 <html lang="..."> (或任何其他 DOM 标签名) 和 <link ... hreflang="..."> 的 BCP 47 语言标签。
- 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 的功能仍在开发中。

`future`

类型：Object

future 配置对象允许你选择性地启用即将推出、不稳定或实验性的，尚未完全成熟的道格龙（Docusaurus）功能。

它也是一种让你提前采纳下一主要版本中即将到来的重大变更的方式，从而使你能够在停留在当前版本的同时，为下一个版本做好准备。Remix Future Flags 这篇博文极好地解释了这一理念。

次要版本中的重大变更

以 experimental_ 或 unstable_ 为前缀的功能可能会在 次要版本 中发生变化，并且不被视为语义化版本（Semantic Versioning）的重大变更。

以 v<MajorVersion> (v6 v7 等) 为命名空间的功能是未来标志，预计在下一个主要版本中会默认开启。这些功能发生变化的可能性较小，但我们保留了这样做的可能性。

future API 的重大变更应该易于处理，并将在次要/主要版本的博文中进行说明。

示例：

docusaurus.config.js
export default {
  future: {
    v4: {
      removeLegacyPostBuildHeadAttribute: true,
      useCssCascadeLayers: true,
    },
    experimental_faster: {
      swcJsLoader: true,
      swcJsMinimizer: true,
      swcHtmlMinimizer: true,
      lightningCssMinimizer: true,
      rspackBundler: true,
      rspackPersistentCache: true,
      ssgWorkerThreads: true,
      mdxCrossCompilerCache: true,
    },
    experimental_storage: {
      type: 'localStorage',
      namespace: true,
    },
    experimental_router: 'hash',
  },
};

v4：允许你选择性启用即将到来的道格龙（Docusaurus）v4 版本的重大变更和功能，以便提前为这个新版本准备好你的网站。使用 true 作为快捷方式可以启用所有标志。
- removeLegacyPostBuildHeadAttribute：移除旧版的 plugin.postBuild({head}) API，该 API 阻止了我们应用有用的 SSG 优化（解释）。
- useCssCascadeLayers：这将启用道格龙（Docusaurus）CSS 级联层插件，并使用我们计划为道格龙（Docusaurus）v4 默认应用的预配置层。
experimental_faster：一个包含功能标志的对象，旨在使道格龙（Docusaurus）的构建速度更快。这需要在你的网站依赖中添加 @docusaurus/faster 包。使用 true 作为快捷方式可以启用所有标志。在 Docusaurus Faster 问题中有更多信息。可用的功能标志：
- swcJsLoader：使用 SWC 来转译 JS（替代 Babel）。
- swcJsMinimizer：使用 SWC 来压缩 JS（替代 Terser）。
- swcHtmlMinimizer ：使用 SWC 来压缩 HTML 和内联的 JS/CSS（替代 html-minifier-terser）。
- lightningCssMinimizer：使用 Lightning CSS 来压缩 CSS（替代 cssnano 和 clean-css）。
- rspackBundler：使用 Rspack 来打包你的应用（替代 webpack）。
- rspackPersistentCache：使用 Rspack 持久化缓存来在后续构建中更快地重新构建你的应用。需要 rspackBundler: true。需要在重新构建之间持久化 ./node_modules/.cache。
- mdxCrossCompilerCache：为浏览器/Node.js 环境编译 MDX 文件时只编译一次，而不是两次。
- ssgWorkerThreads：使用 Node.js 工作线程池来更快地执行静态站点生成阶段。需要开启 future.v4.removeLegacyPostBuildHeadAttribute。
experimental_storage：主题作者应努力遵循的全站浏览器存储选项。
- type：主题作者应使用的浏览器存储类型。可能的值是 localStorage 和 sessionStorage。默认为 localStorage。
- namespace：是否为浏览器存储键添加命名空间，以避免当多个道格龙（Docusaurus）网站托管在同一域名下或本地主机上时发生存储键冲突。可能的值是 string | boolean。命名空间会附加到存储键的末尾，格式为 key-namespace。使用 true 可根据你的网站 url + baseUrl 自动生成一个随机命名空间。默认为 false（无命名空间，历史行为）。
experimental_router：要使用的路由器类型。可能的值是 browser 和 hash。默认为 browser。hash 路由器仅在极少数情况下有用，例如当你希望退出静态站点生成，拥有一个完全客户端的应用，且只有一个 index.html 入口文件时。这对于将道格龙（Docusaurus）网站作为 .zip 归档文件分发，并且无需运行 Web 服务器即可在本地浏览非常有用。

`noIndex`

类型：boolean

此选项会向每个页面添加 <meta name="robots" content="noindex, nofollow"> 标签，以告知搜索引擎不要索引你的网站（更多信息请参见此处）。

示例：

docusaurus.config.js
export default {
  noIndex: true, // 默认为 `false`
};

`onBrokenLinks`

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

当道格龙（Docusaurus）检测到任何损坏的链接时的行为。

默认情况下，它会抛出一个错误，以确保你永远不会发布任何损坏的链接。

备注

损坏链接检测仅在生产构建（docusaurus build）时可用。

`onBrokenAnchors`

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

当道格龙（Docusaurus）检测到任何使用道格龙（Docusaurus）的 Heading 组件声明的损坏锚点时的行为。

默认情况下，它会打印一条警告，让你知道你的锚点已损坏。

`onBrokenMarkdownLinks`

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

当道格龙（Docusaurus）检测到任何损坏的 Markdown 链接时的行为。

默认情况下，它会打印一条警告，让你知道你的 Markdown 链接已损坏。

`onDuplicateRoutes`

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

当道格龙（Docusaurus）检测到任何重复路由时的行为。

默认情况下，它会在你运行 yarn start 或 yarn build 后显示一条警告。

`tagline`

类型：string

你网站的标语。

docusaurus.config.js
export default {
  tagline:
    '道格龙（Docusaurus）让维护开源文档网站变得简单。',
};

`organizationName`

类型：string

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

docusaurus.config.js
export default {
  // 道格龙（Docusaurus）的组织是 facebook
  organizationName: 'facebook',
};

`projectName`

类型：string

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

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

`deploymentBranch`

类型：string

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

docusaurus.config.js
export default {
  deploymentBranch: 'gh-pages',
};

`githubHost`

类型：string

你的服务器的主机名。如果你正在使用 GitHub Enterprise，这个字段会很有用。如果你不使用 docusaurus deploy 命令，则不需要此字段。

docusaurus.config.js
export default {
  githubHost: 'github.com',
};

`githubPort`

类型：string

你的服务器的端口。如果你正在使用 GitHub Enterprise，这个字段会很有用。如果你不使用 docusaurus deploy 命令，则不需要此字段。

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

`themeConfig`

类型：Object

用于自定义你网站 UI（如导航栏和页脚）的主题配置对象。

示例：

docusaurus.config.js
export default {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: false,
        autoCollapseCategories: false,
      },
    },
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: true,
    },
    navbar: {
      title: '网站标题',
      logo: {
        alt: '网站 Logo',
        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 开源 Logo',
        src: 'img/meta_oss_logo.png',
        href: 'https://opensource.fb.com',
        width: 160,
        height: 51,
      },
      copyright: `版权所有 © ${new Date().getFullYear()} Facebook, Inc.`, // 你也可以在这里放入自己的 HTML
    },
  },
};

`plugins`

类型：PluginConfig[]

type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];

关于 PluginModule 的结构，请参阅插件方法参考。

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

`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 配置。

类型：MarkdownConfig

type MarkdownPreprocessor = (args: {
  filePath: string;
  fileContent: string;
}) => string;

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

export type ParseFrontMatter = (params: {
  filePath: string;
  fileContent: string;
  defaultParseFrontMatter: ParseFrontMatter;
}) => Promise<{
  frontMatter: {[key: string]: unknown};
  content: string;
}>;

type MarkdownAnchorsConfig = {
  maintainCase: boolean;
};

type MarkdownConfig = {
  format: 'mdx' | 'md' | 'detect';
  mermaid: boolean;
  preprocessor?: MarkdownPreprocessor;
  parseFrontMatter?: ParseFrontMatter;
  mdx1Compat: MDX1CompatOptions;
  remarkRehypeOptions: object; // 参见 https://github.com/remarkjs/remark-rehype#options
  anchors: MarkdownAnchorsConfig;
};

示例：

docusaurus.config.js
export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    parseFrontMatter: async (params) => {
      // 首先，等待默认的 front matter 解析器完成
      const result = await params.defaultParseFrontMatter(params);
      // 然后，你可以修改 front matter
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
      // 最后，返回修改后的结果
      return result;
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
    anchors: {
      maintainCase: true,
    },
  },
};

名称	类型	默认值	描述
`format`	`'mdx' \| 'md' \| 'detect'`	`'mdx'`	用于 Markdown 内容的默认解析器格式。使用 'detect' 将根据文件扩展名（`.md` vs `.mdx`）自动选择合适的格式。
`mermaid`	`boolean`	`false`	当为 `true` 时，允许道格龙（Docusaurus）将带有 `mermaid` 语言的 Markdown 代码块渲染为 Mermaid 图。
`preprocessor`	`MarkdownPreprocessor`	`undefined`	让你能够在解析前修改 Markdown 内容字符串。请将其作为最后的应急手段或变通方法使用：实现一个 Remark/Rehype 插件几乎总是更好的选择。
`parseFrontMatter`	`ParseFrontMatter`	`undefined`	让你能够提供自己的 front matter 解析器，或增强默认的解析器。详情请阅读我们的 front matter 指南。
`mdx1Compat`	`MDX1CompatOptions`	`{comments: true, admonitions: true, headingIds: true}`	兼容性选项，以便更容易地升级到道格龙（Docusaurus）v3+。
`anchors`	`MarkdownAnchorsConfig`	`{maintainCase: false}`	用于控制从 Markdown 标题生成的锚点行为的选项。
`remarkRehypeOptions`	`object`	`undefined`	可以传递自定义的 `remark-rehype` 选项。

`customFields`

道格龙（Docusaurus）会阻止 docusaurus.config.js 中出现未知字段。要添加自定义字段，请在 customFields 中定义它。

类型：Object

docusaurus.config.js
export default {
  customFields: {
    admin: 'endi',
    superman: 'lol',
  },
};

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

错误：字段 'foo'、'bar' 在 docusaurus.config.js 中无法识别

`staticDirectories`

一个路径数组，可以是相对于网站目录的相对路径或绝对路径。这些路径下的文件将被原样复制到构建输出目录中。

类型：string[]

示例：

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

`headTags`

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

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

示例：

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

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

`scripts`

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

请注意，此处添加的 <script> 是渲染阻塞的，因此你可能希望向对象中添加 async: true/defer: true。

类型：(string | Object)[]

示例：

docusaurus.config.js
export default {
  scripts: [
    // 字符串格式。
    'https://docusaurus.io/script.js',
    // 对象格式。
    {
      src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
      async: true,
    },
  ],
};

`stylesheets`

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

类型：(string | Object)[]

示例：

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

信息

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

`clientModules`

一个在你的网站上全局加载的客户端模块数组。

示例：

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

`ssrTemplate`

一个用 Eta 语法编写的 HTML 模板，将用于渲染你的应用程序。这可以用来在 body 标签上设置自定义属性、添加额外的 meta 标签、自定义 viewport 等。请注意，道格龙（Docusaurus）将依赖于模板的正确结构才能正常工作，一旦你自定义了它，你将必须确保你的模板符合上游的要求。

类型：string

示例：

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> 标签中的标题分隔符。

示例：

docusaurus.config.js
export default {
  titleDelimiter: '🦖', // 默认为 `|`
};

`baseUrlIssueBanner`

类型：boolean

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

示例：

docusaurus.config.js
export default {
  baseUrlIssueBanner: true, // 默认为 `true`
};

一个 baseUrl 问题横幅的示例。由于样式表加载失败，样式非常原始。文本内容是"你的道格龙（Docusaurus）网站没有正确加载... 当前配置的 baseUrl = / (默认值); 我们建议尝试 baseUrl = /build/"

注意

由于 baseUrl 错误导致所有资源加载失败时，此横幅需要内联 CSS / JS。

如果你有严格的内容安全策略 (Content Security Policy)，你应该禁用它。

概述​

必填字段​

title​

url​

baseUrl​

可选字段​

favicon​

trailingSlash​

i18n​

future​

noIndex​

onBrokenLinks​

onBrokenAnchors​

onBrokenMarkdownLinks​

onDuplicateRoutes​

tagline​

organizationName​

projectName​

deploymentBranch​

githubHost​

githubPort​

themeConfig​

plugins​

themes​

presets​

markdown​

customFields​

staticDirectories​

headTags​

scripts​

stylesheets​

clientModules​

ssrTemplate​

titleDelimiter​

baseUrlIssueBanner​

概述