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

配置

Docusaurus 对配置文件有着独特见解。 我们鼓励您将站点信息集中到一处。 我们将维护此文件的每个字段,并让其可以在您站点的任何地方被使用。

悉心维护的 docusaurus.config.js 将让您在自定义站点的同时,帮助您、您的协作者及开源项目贡献者能更专心于文档网站本身。

docusaurus.config.js 里会写什么?

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

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

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

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

站点元数据

站点元数据包含 titleurlbaseUrlfavicon 在内的重要全局元数据。

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.

部署配置

使用 deploy 命令时将使用 projectNameorganizationName ,以及 deploymentBranch 等作为部署选项。

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

主题、插件和预设配置

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 配置

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

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

大多情况下,这份配置就已足够。 如果您想自定义您的 babel 配置(例如添加对 Flow 的支持),您可以直接编辑此文件。 要使您的更改生效,您需要重新启动 Docusaurus 开发服务器。