第4章 Docusaurus 配置详解

版本：2.x配置 Docusaurus 对配置有自己的独特设计：我们鼓励你把站点的相关信息集中到一处。Docusaurus 会守护这个文件中的字段，并让这些数据对象在整个站点中都可以方便地访问。 维护好一份 docusaurus.config.js，能让你、你的协作者以及开源贡献者专注于文档本身，同时又能灵活定制站点。 docusaurus.config.js 里应该放什么？​ 即使你是在开发自己的站点，也不必从零开始编写 docusaurus.config.js。所有模板都自带一份 docusaurus.config.js，其中包含了常用选项的默认值。 不过，对配置的设计和实现方式有一个整体了解会对你有所帮助。 Docusaurus 配置大致可以分为以下几类： 站点元数据、部署配置、主题/插件/预设配置、自定义配置 关于每个可配置字段的详细说明，请参考 docusaurus.config.js API 参考文档。 站点元数据​ 站点元数据包含一些基础的全局信息，例如 title、url、baseUrl 和 favicon。 它们会在多个地方用到：站点的标题和页眉、浏览器标签页图标、社交分享（Facebook、X）信息，甚至用于生成静态文件的正确访问路径。 部署配置​ projectName、organizationName 以及可选的 deploymentBranch 等部署配置，会在你使用 deploy 命令部署站点时用到。 建议查阅部署文档了解更多信息。 主题、插件和预设配置​ 分别通过 themes、plugins 和 presets 字段列出站点使用的主题、插件和预设。它们通常是 npm 包： docusaurus.config.jsmodule.exports = {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};
提示：Docusaurus 支持模块简写，可以把上面的配置简化为： docusaurus.config.jsmodule.exports = {
// ...
plugins: ['content-blog', 'content-pages'],
themes: ['classic'],
};
它们也可以从本地目录加载： docusaurus.config.jsconst path = require('path');

module.exports = {
// ...
themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};
若需为插件或主题设置选项，请在配置文件中将该插件或主题的名称替换为一个数组，数组内包含该名称及其选项对象： docusaurus.config.jsmodule.exports = {
// ...
plugins: [
[
'content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'content-pages',
],
};
若需为预设（preset）中捆绑的插件或主题设置选项，请通过 `presets` 字段传递这些选项。在下例中，`docs` 指向 @docusaurus/plugin-content-docs，`theme` 指向 @docusaurus/theme-classic。 docusaurus.config.jsmodule.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
提示：`presets: [['classic', {...}]]` 这种简写形式同样有效。 关于配置主题、插件和预设的更多帮助，请参阅《使用插件》。 自定义配置 Docusaurus 会拦截 `docusaurus.config.js` 中未识别的字段。若要添加自定义字段，需在 `customFields` 中定义。 示例： docusaurus.config.jsmodule.exports = {
// ...
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 ;
};
提示：如果你只需在客户端使用这些字段，完全可以创建自己的 JS 文件并作为 ES6 模块导入，无需将其放入 `docusaurus.config.js`。 自定义 Babel 配置 对于新的 Docusaurus 项目，我们已在项目根目录自动生成 `babel.config.js`。 babel.config.jsmodule.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};

大多数情况下，此配置即可正常工作。如需自定义 Babel 配置（例如添加对 Flow 的支持），可直接编辑该文件。请注意，更改需重启 Docusaurus 开发服务器方能生效。