跳到主要内容
版本:2.2.0

配置

Docusaurus 对配置文件有着独特见解。 我们鼓励你将站点信息集中到一处。 我们会维护这个文件的每个字段,你可以在站点的任何地方访问数据对象。

悉心维护的 docusaurus.config.js 能够让你在个性化站点的同时,帮助你、你的协作者、以及开源项目贡献者专注于文档本身。

docusaurus.config.js 里会写什么?

即便你正在开发网站,你也没必要从零开始撰写 docusaurus.config.js。 所有模板都自带了一个 docusaurus.config.js,包含常见选项的默认值。

但是,深入了解配置是如何设计与实现的也会很有帮助。

从高维度来说,Docusaurus 配置可被分为这几类:

For exact reference to each of the configurable fields, you may refer to docusaurus.config.js API reference.

站点元数据

站点元数据包括了 titleurlbaseUrlfavicon 等重要全局元数据。

你的站点的许多地方都会用到这些信息,比如标题、节标题、浏览器选项卡图标、社交网站信息 (Facebook, Twitter),等等。如果缺少这些信息,甚至不能生成正确的静态文件路径。

部署配置

使用 deploy 命令时,会用到 projectNameorganizationNamedeploymentBranch 等部署选项。

我们推荐你参考部署文档以了解详情。

主题、插件和预设配置

List the themes, plugins, and presets for your site in the themes, plugins, and presets fields, respectively. 这些通常为 npm 软件包:

docusaurus.config.js
module.exports = {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};
提示

Docusaurus supports module shorthands, allowing you to simplify the above configuration as:

docusaurus.config.js
module.exports = {
// ...
plugins: ['content-blog', 'content-pages'],
themes: ['classic'],
};

这些模块也可以从本地目录加载:

docusaurus.config.js
const path = require('path');

module.exports = {
// ...
themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};

要指定插件或主题选项,请将配置文件的插件或主题名称替换一个二元组,包含了名称及配置选项对象:

docusaurus.config.js
module.exports = {
// ...
plugins: [
[
'content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'content-pages',
],
};

预设中内置的插件或主题的选项需要经由 presets 字段传递。 这个例子里,docs 代表了 @docusaurus/plugin-content-docs,而 theme 代表了 @docusaurus/theme-classic

docusaurus.config.js
module.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.js
module.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 <div>{`${title} · ${tagline}`}</div>;
};
提示

如果你只想在客户端使用这些字段,你可以把它们放在单独的 JS 文件中,然后在组件中把它们作为 ES6 模块导入,没有必要放在 docusaurus.config.js 里。

自定义 Babel 配置

我们会在新 Docusaurus 项目的根目录自动生成 babel.config.js

babel.config.js
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};

大多数情况下,这个配置已经够用了。 如果你想要自定义你的 Babel 配置(比如添加 Flow 支持),你可以直接编辑这个文件。 你需要重新启动 Docusaurus 开发服务器,更改才能生效。