跳到主要内容
版本:Canary 🚧

配置

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

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

docusaurus.config.js 里会写什么?

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

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

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

docusaurus.config.js API 文档 列出了每一个配置选项的详细介绍。

站点元数据

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

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

部署配置

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

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

主题、插件和预设配置

themespluginspresets 字段中,分别列出你的网站用到的主题插件预设。 这些通常为 npm 软件包:

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

Docusaurus 支持模块名简写,从而允许你把上述的配置简化成:

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 开发服务器,更改才能生效。