跳到主要内容

配置

Docusaurus 具有独特的配置。我们鼓励您将网站相关的信息集中到一个地方。我们提供对配置文件中各个字段的保护，并使此数据可以在整个网站中访问。

维护好 docusaurus.config.js 文件对您、您的合作者和您的开源项目的贡献者都有帮助，这让大家能够将关注点放到文档上，同时仍然能够对网站进行自定义。

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

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

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

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

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

网站的元数据​

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

这些数据被用于网站的多个位置，例如网站的标题（site's title）和主标题（headings）、浏览器选项卡上的图标、社交分享（Facebook、Twitter）、甚至为生成的静态文件提供正确的文件路径。

部署配置​

当你通过 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 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>;
};
提示

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

自定义 Babel 配置​

对于新建的 Docusaurus 项目，我们会自动生成一份 babel.config.js 配置文件并放置于项目的根目录下。

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

大多数时候，此配置文件都能工作良好。如果你要自定义 Babel 的配置信息的话（例如添加对 Flow 的支持），你可以直接编辑此文件。但是需要重启 Docusaurus 的开发服务器才能使更改生效。