Skip to main content
Version: 3.7.0

docusaurus.config.js

info

请参考入门指南中的配置部分以获取示例。

概述

docusaurus.config.js 包含您网站的配置,并放置在您网站的根目录中。

note

使用TypeScript的Docusaurus代码库时,您的配置文件可能被称为docusaurus.config.ts。其语法与js配置文件大致相同,只是增加了类型。您可以在Docusaurus网站上看到一个示例。

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

docusaurus.config.js 文件支持:

示例:

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

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

必填字段

title

  • 类型: string

您网站的标题。将用于元数据并作为浏览器标签标题。

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

url

  • 类型: string

您网站的URL。这也可以被视为顶级主机名。例如,https://facebook.github.iohttps://facebook.github.io/metro/ 的URL,而 https://docusaurus.iohttps://docusaurus.io 的URL。此字段与 baseUrl 字段相关。

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

baseUrl

  • 类型: string

您网站的基础URL。可以视为主机之后的路径。例如,/metro/https://facebook.github.io/metro/的基础URL。对于没有路径的URL,基础URL应设置为/。此字段与url字段相关。始终包含前导和尾随斜杠。

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

可选字段

favicon

  • 类型: string | undefined

您网站图标的路径;必须是一个可以在链接的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
tip

每个静态托管提供商提供静态文件的方式都不同(这种行为甚至可能随时间变化)。

请参考部署指南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) 将用于标签
  • locales: 部署在您站点上的语言环境列表。必须包含 defaultLocale
  • path: 所有本地化文件夹的根文件夹路径。可以是绝对路径或相对于配置文件的路径。默认为 i18n
  • localeConfigs: 每个语言环境的单独选项。
    • label: 在语言环境下拉菜单中显示此语言环境的标签。
    • direction: ltr(默认)或 rtl(用于从右到左的语言,如波斯语、阿拉伯语、希伯来语等)。用于选择语言环境的CSS和HTML元属性。
    • htmlLang: 用于(或任何其他DOM标签名称)和的BCP 47语言标签。
    • calendar: 用于计算日期纪元的日历。请注意,它不控制实际显示的字符串:MM/DD/YYYYDD/MM/YYYY都是gregory。要选择格式(DD/MM/YYYYMM/DD/YYYY),请将您的语言环境名称设置为en-GBen-USen表示en-US)。
    • path: 此语言环境的所有插件本地化文件夹的相对根文件夹。将相对于i18n.path解析。默认为语言环境的名称。注意:这对语言环境的baseUrl没有影响——自定义基本URL正在进行中。

future

  • 类型:Object

future 配置对象允许选择加入尚未准备好正式推出的即将推出/不稳定/实验性的 Docusaurus 功能。

这也是一种选择加入即将到来的重大变更的方式,使您能够为下一个版本准备您的网站,同时保持在之前的版本上。Remix Future Flags 博客文章很好地解释了这个想法。

Breaking changes in minor versions

experimental_unstable_为前缀的功能在次要版本中可能会发生变化,并且不被视为语义版本控制的破坏性更改

v_v6_ v7_等)为前缀的功能是未来标志,预计在下一个主要版本中默认启用。这些功能不太可能发生变化,但我们保留这样做的可能性。

future API的破坏性更改应该易于处理,并且会在次要/主要版本的博客文章中记录。

示例:

docusaurus.config.js
export default {
future: {
experimental_faster: {
swcJsLoader: true,
swcJsMinimizer: true,
swcHtmlMinimizer: true,
lightningCssMinimizer: true,
rspackBundler: true,
mdxCrossCompilerCache: true,
},
experimental_storage: {
type: 'localStorage',
namespace: true,
},
experimental_router: 'hash',
},
};
  • experimental_faster: 一个包含功能标志的对象,用于使Docusaurus构建更快。这需要将@docusaurus/faster包添加到您站点的依赖项中。使用true作为启用所有标志的简写。在Docusaurus Faster问题上阅读更多内容。可用的功能标志:
  • experimental_storage: 主题作者应努力尊重的站点范围的浏览器存储选项。
    • type: 主题作者应使用的浏览器存储类型。可能的值为 localStoragesessionStorage。默认为 localStorage
    • namespace: 是否对浏览器存储键进行命名空间处理,以避免在 Docusaurus 站点托管在同一域名下或本地主机时发生存储键冲突。可能的值为 string | boolean。命名空间会附加在存储键的末尾 key-namespace。使用 true 从您的站点 url + baseUrl 自动生成一个随机命名空间。默认为 false(无命名空间,历史行为)。
  • experimental_router: 使用的路由器类型。可能的值为 browserhash。默认为 browserhash 路由器仅在极少数情况下有用,即您希望退出静态站点生成,拥有一个完全客户端的应用程序,并且只有一个 index.html 入口文件。这对于将 Docusaurus 站点分发为 .zip 存档文件非常有用,您可以在不运行 Web 服务器的情况下本地浏览

noIndex

  • 类型: boolean

此选项将添加到每个页面,以告诉搜索引擎避免索引您的网站(更多信息这里)。

示例:

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

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

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

note

断链检测仅适用于生产构建(docusaurus build)。

onBrokenAnchors

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

Docusaurus 在检测到使用 Docusaurus 的 Heading 组件声明的任何损坏锚点时的行为。

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

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

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

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

onDuplicateRoutes

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

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

默认情况下,在运行 yarn startyarn build 后会显示警告。

tagline

  • 类型: string

您网站的标语。

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

organizationName

  • 类型: string

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

docusaurus.config.js
export default {
// Docusaurus' organization is 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: '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的结构。

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

  • 类型: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; // see 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) => {
const result = await params.defaultParseFrontMatter(params);
result.frontMatter.description =
result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
return result;
},
mdx1Compat: {
comments: true,
admonitions: true,
headingIds: true,
},
anchors: {
maintainCase: true,
},
},
};
NameTypeDefaultDescription
format'mdx' | 'md' | 'detect''mdx'The default parser format to use for Markdown content. Using 'detect' will select the appropriate format automatically based on file extensions: .md vs .mdx.
mermaidbooleanfalseWhen true, allows Docusaurus to render Markdown code blocks with mermaid language as Mermaid diagrams.
preprocessorMarkdownPreprocessorundefinedGives you the ability to alter the Markdown content string before parsing. Use it as a last-resort escape hatch or workaround: it is almost always better to implement a Remark/Rehype plugin.
parseFrontMatterParseFrontMatterundefinedGives you the ability to provide your own front matter parser, or to enhance the default parser. Read our front matter guide for details.
mdx1CompatMDX1CompatOptions{comments: true, admonitions: true, headingIds: true}Compatibility options to make it easier to upgrade to Docusaurus v3+.
anchorsMarkdownAnchorsConfig{maintainCase: false}Options to control the behavior of anchors generated from Markdown headings
remarkRehypeOptionsobjectundefinedMakes it possible to pass custom remark-rehype options.

customFields

Docusaurus 保护 docusaurus.config.js 免受未知字段的影响。要添加自定义字段,请在 customFields 上定义它。

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

尝试在配置中添加未知字段将在构建时导致错误:

Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js

staticDirectories

一组路径,相对于站点的目录或绝对路径。这些路径下的文件将按原样复制到构建输出中。

  • 类型: string[]

示例:

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

headTags

一组将插入到HTML 中的标签。这些值必须是包含两个属性的对象;tagNameattributestagName 必须是一个字符串,用于确定要创建的标签;例如 "link"attributes 必须是一个属性-值的映射。

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

示例:

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

这将变成在生成的HTML中。

scripts

要加载的脚本数组。值可以是字符串或属性-值映射的普通对象。

请注意,这里添加的

  • 类型: (string | Object)[]

示例:

docusaurus.config.js
export default {
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源数组。值可以是字符串或属性-值映射的普通对象。标签将被插入到HTML的 中。如果使用对象,唯一必需的属性是href,并且允许任何其他属性(每个属性应具有布尔/字符串值)。

  • 类型: (string | Object)[]

示例:

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

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

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

将用作生成的标签中的标题分隔符。

示例:

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

baseUrlIssueBanner

  • 类型: boolean

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

示例:

docusaurus.config.js
export default {
baseUrlIssueBanner: true, // Defaults to `true`
};

一个示例的基本URL问题横幅。样式非常原始,因为样式表未能加载。文本显示“您的Docusaurus站点未能正确加载...当前配置的baseUrl = /(默认值);我们建议尝试baseUrl = /build/

warning

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

如果您有严格的内容安全策略,您应该禁用它。