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

配置

Docusaurus 对配置文件有着独特见解。 我们鼓励您将站点信息聚合至一处。 我们将维护此文件的每个字段,并让其可被您站点的每个角落所使用。

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

docusaurus.config.js 里会写什么?

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

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

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

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

站点元数据

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

您站点的诸多位置,如标题、页眉、浏览器图标、社交网站分享(Facebook、Twitter)或甚至在生成正确位置的静态文件时,都将使用这些信息。

部署配置

使用 deploy 命令时将使用如 projectNameorganizationName 在内的部署选项。

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

主题、插件和预设配置

分别列出位于 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-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')],
},
},
],
],
};

欲获取主题、插件及预设的进一步帮助,请参见使用主题使用插件使用预设

自定义配置

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 配置。 要使您的更改生效,您需要重新启动 Docusaurus 开发服务器。