跳到主要内容

配置

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

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

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

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

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

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

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

网站的元数据#

网站的元数据包含基本的全局元数据，例如 title、url、baseUrl 和 favicon。

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

部署配置#

当你通过 deploy 命令部署网站时，将使用到诸如 projectName 和 organizationName 这列的配置信息。

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

主题、插件和预设配置#

在 themes、plugins 和 presets 字段中分别列出网站的 主题、插件 和 预设。这些通常是 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

If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in docusaurus.config.js.

自定义 Babel 配置#

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

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

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

编辑此页