Skip to main content

配置

Docusaurus 具有独特的配置。我们鼓励您将网站信息汇总到一个地方。我们对此文件中的配置字段提供了保护,并为在站点中访问此数据对象提供了便利。

保持对 docusaurus.config.js 文件的良好维护可以为您、您的协作者和开放源码提供者提供帮助,在专注于文档的同时仍可以自定义站点。

docusaurus.config.js 文件中有什么内容?

即使您正在开发网站,也不必从头开始编写 docusaurus.config.js。所有模板都带有一个 docusaurus.config.js 文件,其中包含了常用选项的默认值。

但是,如果您对配置文件的设计和实现有一个高屋建瓴的了解,将很有帮助。

Docusaurus 的配置总体可分为以下几类:

有关每个可配置字段的确切参考,请参考 docusaurus.config.js API 手册

网站的元数据

网站的元数据包含基本的全局元数据,例如 titleurlbaseUrlfavicon

这些元数据在许多地方被使用到,例如网站的标题、用于在浏览器标签页上显示的图标、social sharing (Facebook, Twitter) information ,甚至为你的静态文件生成正确的路径。

部署配置

当你通过 deploy 命令部署网站时,将使用到诸如 projectNameorganizationName 甚至是 deploymentBranch 这类的配置信息。

建议查看 部署 相关的文档以了解更多信息。

主题、插件和预设配置

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

docusaurus.config.js
module.exports = {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-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: [
[
'@docusaurus/plugin-content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'@docusaurus/plugin-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')],
},
},
],
],
};

如需获得更多关于配置主题、插件和预设的帮助信息,请参见这些文档: 使用主题使用插件使用预设

自定义配置

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>;
};
tip

如果你只是想在客户端使用配置信息中的这些字段,则需要你自己创建 JS 文件并将其作为 ES6 模块导入(import),而无需将它们放到 docusaurus.config.js 配置文件中。

自定义 Babel 配置

对于新创建的 Docusaurus 项目,我们会自动在项目的根目录下生成一个 babel.config.js 文件。

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

在大多数情况下,该配置文件都能正常工作。如果你想对其进行自定义,则可以直接编辑此文件以自定义 babel 的配置。为了使更改生效,你需要重启 Docusaurus 的开发服务器。