配置
查看 docusaurus.config.js API 参考 以获取所有选项的完整列表。
Docusaurus 对配置有独特的看法。我们鼓励您将有关您网站的信息集中到一个地方。我们保护此文件中的字段，并促进在整个网站中访问此数据对象。
维护良好的 docusaurus.config.js 有助于您、您的合作者和您的开源贡献者专注于文档，同时仍然能够自定义网站。
声明 docusaurus.config.js 的语法
docusaurus.config.js 文件在 Node.js 中运行，应导出以下任一内容：
- 一个 配置对象
- 一个 函数，该函数创建配置对象
docusaurus.config.js 文件支持以下内容：
约束
- 必需：使用
export default /* your config*/（或module.exports来导出您的 Docusaurus 配置） - 可选：使用
import Lib from 'lib'（或require('lib')）来导入 Node.js 包
Docusaurus 使我们能够以各种 等效方式 声明其配置，并且以下所有配置示例都将产生完全相同的结果
export default {
title: 'Docusaurus',
url: 'https://docusaurus.org.cn',
// your site config ...
};
module.exports = {
title: 'Docusaurus',
url: 'https://docusaurus.org.cn',
// your site config ...
};
import type {Config} from '@docusaurus/types';
export default {
title: 'Docusaurus',
url: 'https://docusaurus.org.cn',
// your site config ...
} satisfies Config;
const config = {
title: 'Docusaurus',
url: 'https://docusaurus.org.cn',
// your site config ...
};
export default config;
export default function configCreator() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.org.cn',
// your site config ...
};
}
export default async function createConfigAsync() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.org.cn',
// your site config ...
};
}
使用异步配置创建器对于导入 ESM 仅限模块（尤其是大多数 Remark 插件）很有用。由于动态导入，可以导入此类模块
export default async function createConfigAsync() {
// Use a dynamic import instead of require('esm-lib')
const lib = await import('lib');
return {
title: 'Docusaurus',
url: 'https://docusaurus.org.cn',
// rest of your site config...
};
}
docusaurus.config.js 中包含什么内容？
即使您正在开发您的网站，您也不必从头开始编写 docusaurus.config.js。所有模板都附带一个 docusaurus.config.js，其中包含常用选项的默认值。
但是，如果您对配置的设计和实现方式有一个高级理解，这将非常有帮助。
Docusaurus 配置的高级概述可以分为以下几类：
网站元数据
网站元数据包含必要的全局元数据，例如 title、url、baseUrl 和 favicon。
它们在多个地方使用，例如您的网站标题和标题、浏览器标签图标、社交分享（Facebook、Twitter）信息，甚至用于生成提供静态文件的正确路径。
部署配置
部署配置（例如 projectName、organizationName 以及可选的 deploymentBranch）在您使用 deploy 命令部署网站时使用。
建议查看 部署文档 以获取更多信息。
主题、插件和预设配置
分别在 themes、plugins 和 presets 字段中列出您网站的 主题、插件 和 预设。这些通常是 npm 包
export default {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};
Docusaurus 支持 模块简写，允许您简化上述配置为
export default {
// ...
plugins: ['content-blog', 'content-pages'],
themes: ['classic'],
};
它们也可以从本地目录加载
import path from 'path';
export default {
// ...
themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};
要为插件或主题指定选项，请将配置文件中插件或主题的名称替换为包含名称和选项对象的数组
export default {
// ...
plugins: [
[
'content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'content-pages',
],
};
要为预设中捆绑的插件或主题指定选项，请通过 presets 字段传递选项。在此示例中，docs 指的是 @docusaurus/plugin-content-docs，theme 指的是 @docusaurus/theme-classic。
export default {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
theme: {
customCss: ['./src/css/custom.css'],
},
},
],
],
};
presets: [['classic', {...}]] 简写也适用。
如需进一步了解主题、插件和预设的配置帮助，请参阅 使用插件。
自定义配置
Docusaurus 会保护 docusaurus.config.js 免受未知字段的侵害。要添加自定义字段，请在 customFields 中定义它们。
示例
export default {
// ...
customFields: {
image: '',
keywords: [],
},
// ...
};
从组件访问配置
您的配置对象将可供您网站的所有组件使用。您可以通过 React 上下文以 siteConfig 的形式访问它们。
基本示例
import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const Hello = () => {
const {siteConfig} = useDocusaurusContext();
const {title, tagline} = siteConfig;
return <div>{`${title} · ${tagline}`}</div>;
};
如果您只想在客户端使用这些字段，可以创建自己的 JS 文件并将其作为 ES6 模块导入，无需将其放在 docusaurus.config.js 中。
自定义 Babel 配置
对于新的 Docusaurus 项目，我们会在项目根目录中自动生成一个 babel.config.js。
export default {
presets: ['@docusaurus/core/lib/babel/preset'],
};
大多数情况下，此配置都可以正常工作。如果您想自定义 Babel 配置（例如，添加对 Flow 的支持），可以直接编辑此文件。要使您的更改生效，您需要重新启动 Docusaurus 开发服务器。