Skip to main content
版本：2.x

配置

Docusaurus 对配置文件有着独特见解。我们鼓励你将站点信息集中到一处。我们会维护这个文件的每个字段，你可以在站点的任何地方访问数据对象。

悉心维护的 docusaurus.config.js 能够让你在个性化站点的同时，帮助你、你的协作者、以及开源项目贡献者专注于文档本身。

docusaurus.config.js 里会写什么？​

即便你正在开发网站，你也没必要从零开始撰写 docusaurus.config.js。所有模板都自带了一个 docusaurus.config.js，包含常见选项的默认值。

但是，深入了解配置是如何设计与实现的也会很有帮助。

从高维度来说，Docusaurus 配置可被分为这几类：

For exact reference to each of the configurable fields, you may refer to docusaurus.config.js API reference.

站点元数据​

站点元数据包括了 title、url、baseUrl、favicon 等重要全局元数据。

你的站点的许多地方都会用到这些信息，比如标题、节标题、浏览器选项卡图标、社交网站信息 (Facebook, X)甚至静态文件路径的正确生成。

部署配置​

使用 deploy 命令时，会用到 projectName、organizationName、deploymentBranch 等部署选项。

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

主题、插件和预设配置​

将你站点的主题、插件和预设分别填入 themes、plugins 和 presets 字段中。这些通常为 npm 软件包：

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

Docusaurus 支持模块缩写，允许你简化上述配置：

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')],
        },
      },
    ],
  ],
};
提示

你也可以用 presets: [['classic', {...}]] 的简写。

如果在配置主题、插件、预设时需要更多帮助，可以参阅使用插件。

自定义配置​

Docusaurus 不允许 docusaurus.config.js 存在未知字段。要添加自定义字段，请在 customFields 中定义。

示例：

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

在组件中获取配置​

站点中的所有组件都可以访问配置对象。你可以通过 React 上下文中的 siteConfig 字段访问。

简单示例：

import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

const Hello = () => {
  const {siteConfig} = useDocusaurusContext();
  const {title, tagline} = siteConfig;

  return <div>{`${title} · ${tagline}`}</div>;
};
提示

如果你只想在客户端使用这些字段，你可以把它们放在单独的 JS 文件中，然后在组件中把它们作为 ES6 模块导入，没有必要放在 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')],
};

大多数情况下，这个配置已经够用了。如果你想要自定义你的 Babel 配置（比如添加 Flow 支持），你可以直接编辑这个文件。你需要重新启动 Docusaurus 开发服务器，更改才能生效。