跳到主要内容

配置

Docusaurus has a unique take on configurations. 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.

部署配置​

当你通过 deploy 命令部署网站时，将使用到诸如 projectName、organizationName 甚至是 deploymentBranch 这类的配置信息。

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

主题、插件和预设配置​

List the themes, 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'],
};
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-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')],
        },
      },
    ],
  ],
};
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: [],
  },
  // ...
};

在组件中访问配置信息​

你的网站的配置信息可以被所有组件访问到。通过 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

如果你只是想在客户端使用配置信息中的这些字段，则需要你自己创建 JS 文件并将其作为 ES6 模块导入（import），而无需将它们放到 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.