配置

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

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

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 a number of 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 and organizationName are used when you deploy your site with the deploy command.

It is recommended to check the deployment docs for more information.

主题、插件和预设配置

List the theme, plugins, and presets for your site in the themes, plugins, and presets fields, respectively. These are typically npm packages:

docusaurus.config.js
module.exports = {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};

They can also be loaded from local directories:

docusaurus.config.js
const path = require('path');
module.exports = {
// ...
themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};

To specify options for a plugin or theme, replace the name of the plugin or theme in the config file with an array containing the name and an options object:

docusaurus.config.js
module.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'@docusaurus/plugin-content-pages',
],
};

To specify options for a plugin or theme that is bundled in a preset, pass the options through the presets field. In this example, docs refers to @docusaurus/plugin-content-docs and theme refers to @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'),
},
},
],
],
};

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

自定义配置

Docusaurus guards docusaurus.config.js from unknown fields. To add custom fields, define them in customFields.

Example:

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

Accessing configuration from components

Your configuration object will be made available to all the components of your site. And you may access them via React context as siteConfig.

Basic example:

import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const Hello = () => {
const context = useDocusaurusContext();
const {siteConfig = {}} = context;
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.

Customizing Babel Configuration

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

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

Most of the times, this configuration will work just fine. If you want to customize it, you can directly edit this file to customize babel configuration. For your changes to take effect, you need to restart Docusaurus devserver.

Last updated on by wangsai