配置
请查看 docusaurus.config.js API 参考以获取详尽的 选项列表。
Docusaurus 对配置文件有着独特见解。 我们鼓励你将站点信息集中到一处。 我们会维护这个文件的每个字段，你可以在站点的任何地方访问数据对象。
悉心维护的 docusaurus.config.js 能够让你在个性化站点的同时，帮助你、你的协作者、以及开源项目贡献者专注于文档本身。
声明语法 docusaurus.config.js
docusaurus.config.js 该文件在Node js中运行，并且应该导出以下内容:
- 一个 配置对象
- 一个 函数 用来创建配置对象
The docusaurus.config.js file supports:
限制条件：
- 必需的： 使用
export default /* your config*/或者module.exports导出你的 Docusaurus 配置。 - **可选的：**使用
import Lib from 'lib'或者require('lib')导入 Node.js 包
Docusaurus 使我们能够在各种 等价方式 中声明其配置，并且以下所有配置示例都会产生完全相同的结果：
export default {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
module.exports = {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
import type {Config} from '@docusaurus/types';
export default {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
} satisfies Config;
const config = {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
export default config;
export default function configCreator() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
}
export default async function createConfigAsync() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// 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.io',
// rest of your site config...
};
}
docusaurus.config.js 里会写什么？
即便你正在开发网站，你也没必要从零开始撰写 docusaurus.config.js。 所有模板都自带了一个 docusaurus.config.js，包含常见选项的默认值。
但是，深入了解配置是如何设计与实现的也会很有帮助。
从高维度来说，Docusaurus 配置可被分为这几类：
站点元数据
站点元数据包括了 title、url、baseUrl、favicon 等重要全局元数据。
你的站点的许多地方都会用到这些信息，比如标题、节标题、浏览器选项卡图标、社交网站信息 (Facebook, Twitter)，等等。如果缺少这些信息，甚至不能生成正确的静态文件路径。
部署配置
使用 deploy 命令时，会用到 projectName、organizationName、deploymentBranch 等部署选项。
我们推荐你参考部署文档以了解详情。
主题、插件和预设配置
在 themes,、plugins 和 presets 字段中分别列出你的站点的 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 context 中的 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 开发服务器，更改才能生效。