跳转至主内容
Version: 2.0.0-beta.15

配置

Docusaurus 对配置文件有着独特见解。 We encourage you to congregate information about your site into one place. We guard the fields of this file and facilitate making this data object accessible across your site.

Keeping a well-maintained docusaurus.config.js helps you, your collaborators, and your open source contributors to be able to focus on documentation while still being able to customize the site.

docusaurus.config.js 里会写什么?

即便您正在开发网站,您也不应该从零开始撰写 docusaurus.config.js。 所有模板均自带包含常见选项的 docusaurus.config.js

但是,深知配置是如何设计及实现的也很有帮助。

Docusaurus 配置的高阶概览可分为:

要参考每个可配置字段,您可参见 docusaurus.config.js API 文档

站点元数据

Site metadata contains the essential global metadata such as title, url, baseUrl, and favicon.

They are used in several places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information or even to generate the correct path to serve your static files.

部署配置

Deployment configurations such as projectName, organizationName, and optionally deploymentBranch are used when you deploy your site with the deploy command.

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

主题、插件和预设配置

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'],
};
tip

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-docstheme 则指向 @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')],
},
},
],
],
};
tip

The presets: [['classic', {...}]] shorthand works as well.

For further help configuring themes, plugins, and presets, see Using Plugins.

自定义配置

Docusaurus 不允许 docusaurus.config.js 存在未知字段。 要添加自定义字段,请在 customFields 中定义。

示例:

docusaurus.config.js
module.exports = {
// ...
customFields: {
image: '',
keywords: [],
},
// ...
};

在组件中获取配置

您站点的所有组件均可访问配置对象。 您可通过名为 siteConfig 的 React 上下文获取:

简单示例:

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 模块,而无需放入 docusaurus.config.js

自定义 Babel 配置

For new Docusaurus projects, we automatically generated a babel.config.js in the project root.

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

Most of the time, this configuration will work just fine. If you want to customize your babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server.