docusaurus.config.js
请参考入门指南中的配置部分以获取示例。
概述
docusaurus.config.js 包含您网站的配置,并放置在您网站的根目录中。
使用TypeScript的Docusaurus代码库时,您的配置文件可能被称为docusaurus.config.ts。其语法与js配置文件大致相同,只是增加了类型。您可以在Docusaurus网站上看到一个示例。
此文件在Node.js中运行,并且应该导出一个站点配置对象,或者一个创建它的函数。
docusaurus.config.js 文件支持:
示例:
export default {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
export default async function createConfigAsync() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
}
请参考声明docusaurus.config.js的语法以获取更详尽的示例和解释列表。
必填字段
title
- 类型:
string
您网站的标题。将用于元数据并作为浏览器标签标题。
export default {
title: 'Docusaurus',
};
url
- 类型:
string
您网站的URL。这也可以被视为顶级主机名。例如,https://facebook.github.io 是 https://facebook.github.io/metro/ 的URL,而 https://docusaurus.io 是 https://docusaurus.io 的URL。此字段与 baseUrl 字段相关。
export default {
url: 'https://docusaurus.io',
};
baseUrl
- 类型:
string
您网站的基础URL。可以视为主机之后的路径。例如,/metro/是https://facebook.github.io/metro/的基础URL。对于没有路径的URL,基础URL应设置为/。此字段与url字段相关。始终包含前导和尾随斜杠。
export default {
baseUrl: '/',
};
可选字段
favicon
- 类型:
string | undefined
您网站图标的路径;必须是一个可以在链接的href中使用的URL。例如,如果您的图标位于static/img/favicon.ico:
export default {
favicon: '/img/favicon.ico',
};
trailingSlash
- 类型:
boolean | undefined
允许自定义URL/链接末尾斜杠的存在与否,以及静态HTML文件的生成方式:
undefined(默认): 保持URL不变,并为/docs/myDoc.md生成/docs/myDoc/index.htmltrue: 在URL/链接中添加尾部斜杠,并为/docs/myDoc.md生成/docs/myDoc/index.htmlfalse: 从URL/链接中移除尾部斜杠,并为/docs/myDoc.md生成/docs/myDoc.html
每个静态托管提供商提供静态文件的方式都不同(这种行为甚至可能随时间变化)。
请参考部署指南和slorber/trailing-slash-guide以选择适当的设置。
i18n
- 类型:
Object
用于本地化您的站点的i18n配置对象。
示例:
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/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_为前缀的功能在次要版本中可能会发生变化,并且不被视为语义版本控制的破坏性更改。
以v(v6_ v7_等)为前缀的功能是未来标志,预计在下一个主要版本中默认启用。这些功能不太可能发生变化,但我们保留这样做的可能性。
future API的破坏性更改应该易于处理,并且会在次要/主要版本的博客文章中记录。
示例:
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问题上阅读更多内容。可用的功能标志: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)。mdxCrossCompilerCache: 为浏览器/Node.js环境只编译一次MDX文件,而不是两次。
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
此选项将添加到每个页面,以告诉搜索引擎避免索引您的网站(更多信息这里)。
示例:
export default {
noIndex: true, // Defaults to `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
您网站的标语。
export default {
tagline:
'Docusaurus makes it easy to maintain Open Source documentation websites.',
};
organizationName
- 类型:
string
拥有存储库的GitHub用户或组织。如果您不使用docusaurus deploy命令,则不需要此信息。
export default {
// Docusaurus' organization is facebook
organizationName: 'facebook',
};
projectName
- 类型:
string
GitHub 仓库的名称。如果您不使用 docusaurus deploy 命令,则不需要这个。
export default {
projectName: 'docusaurus',
};
deploymentBranch
- 类型:
string
部署静态文件的分支名称。如果您不使用docusaurus deploy命令,则不需要此选项。
export default {
deploymentBranch: 'gh-pages',
};
githubHost
- 类型:
string
服务器的主机名。如果您使用的是GitHub Enterprise,这将非常有用。如果您不使用docusaurus deploy命令,则不需要此信息。
export default {
githubHost: 'github.com',
};
githubPort
- 类型:
string
您的服务器端口。如果您使用的是GitHub Enterprise,这将非常有用。如果您不使用docusaurus deploy命令,则不需要此端口。
export default {
githubPort: '22',
};
themeConfig
- 类型:
Object
用于自定义网站UI(如导航栏和页脚)的主题配置对象。
示例:
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的结构。
export default {
plugins: [
'docusaurus-plugin-awesome',
['docusuarus-plugin-confetti', {fancy: false}],
() => ({
postBuild() {
console.log('Build finished');
},
}),
],
};
themes
- 类型:
PluginConfig[]
export default {
themes: ['@docusaurus/theme-classic'],
};
presets
- 类型:
PresetConfig[]
type PresetConfig = string | [string, any];
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;
};
示例:
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,
},
},
};
| Name | Type | Default | Description |
|---|---|---|---|
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. |
mermaid | boolean | false | When true, allows Docusaurus to render Markdown code blocks with mermaid language as Mermaid diagrams. |
preprocessor | MarkdownPreprocessor | undefined | Gives 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. |
parseFrontMatter | ParseFrontMatter | undefined | Gives you the ability to provide your own front matter parser, or to enhance the default parser. Read our front matter guide for details. |
mdx1Compat | MDX1CompatOptions | {comments: true, admonitions: true, headingIds: true} | Compatibility options to make it easier to upgrade to Docusaurus v3+. |
anchors | MarkdownAnchorsConfig | {maintainCase: false} | Options to control the behavior of anchors generated from Markdown headings |
remarkRehypeOptions | object | undefined | Makes it possible to pass custom remark-rehype options. |
customFields
Docusaurus 保护 docusaurus.config.js 免受未知字段的影响。要添加自定义字段,请在 customFields 上定义它。
- 类型:
Object
export default {
customFields: {
admin: 'endi',
superman: 'lol',
},
};
尝试在配置中添加未知字段将在构建时导致错误:
Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js
staticDirectories
一组路径,相对于站点的目录或绝对路径。这些路径下的文件将按原样复制到构建输出中。
- 类型:
string[]
示例:
export default {
staticDirectories: ['static'],
};
headTags
一组将插入到HTML
中的标签。这些值必须是包含两个属性的对象;tagName 和 attributes。tagName 必须是一个字符串,用于确定要创建的标签;例如 "link"。attributes 必须是一个属性-值的映射。
- 类型:
{ tagName: string; attributes: Object; }[]
示例:
export default {
headTags: [
{
tagName: 'link',
attributes: {
rel: 'icon',
href: '/img/docusaurus.png',
},
},
],
};
这将变成在生成的HTML中。
scripts
要加载的脚本数组。值可以是字符串或属性-值映射的普通对象。
请注意,这里添加的
- 类型:
(string | Object)[]
示例:
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)[]
示例:
export default {
stylesheets: [
// String format.
'https://docusaurus.io/style.css',
// Object format.
{
href: 'http://mydomain.com/style.css',
},
],
};
默认情况下,标签会有rel="stylesheet",但你可以显式地添加一个自定义的rel值来注入任何类型的标签,不一定是样式表。
clientModules
一个要在您的站点上全局加载的客户端模块数组。
示例:
export default {
clientModules: ['./mySiteGlobalJs.js', './mySiteGlobalCss.css'],
};
ssrTemplate
一个用Eta的语法编写的HTML模板,将用于渲染您的应用程序。这可以用于在body标签上设置自定义属性,添加额外的meta标签,自定义viewport等。请注意,Docusaurus将依赖模板的正确结构以正常运行,一旦您自定义了它,您必须确保您的模板符合上游的要求。
- 类型:
string
示例:
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
将用作生成的标签中的标题分隔符。
示例:
export default {
titleDelimiter: '🦖', // Defaults to `|`
};
baseUrlIssueBanner
- 类型:
boolean
启用后,如果您的网站无法加载其CSS或JavaScript文件,将显示一个横幅,这是一个非常常见的问题,通常与网站配置中的错误baseUrl有关。
示例:
export default {
baseUrlIssueBanner: true, // Defaults to `true`
};

此横幅需要内联CSS / JS,以防由于错误的基本URL导致所有资源加载失败。
如果您有严格的内容安全策略,您应该禁用它。