配置

¥Configuration

信息

检查 docusaurus.config.js API 参考 以获得详尽的选项列表。

¥Check the docusaurus.config.js API reference for an exhaustive list of options.

Docusaurus 对配置有独特的看法。我们鼓励你将有关你网站的信息集中到一处。我们保护该文件的字段，并促进在你的站点上访问该数据对象。

¥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.

保持良好的 docusaurus.config.js 可以帮助你、你的合作者和开源贡献者能够专注于文档，同时仍然能够自定义站点。

¥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 的语法

¥Syntax to declare docusaurus.config.js

docusaurus.config.js 文件在 Node.js 中运行，并应导出：

¥The docusaurus.config.js file is run in Node.js and should export either:

• 一个配置对象

  ¥a config object

• 创建配置对象的函数

  ¥a function that creates the config object

信息

docusaurus.config.js 文件支持：

¥The docusaurus.config.js file supports:

• ES 模块

  ¥ES Modules

• CommonJS

• TypeScript

限制条件：

¥Constraints:

• 必需的：使用 export default /* your config*/（或 module.exports 导出 Docusaurus 配置

  ¥Required: use export default /* your config*/ (or module.exports to export your Docusaurus config

• 可选的：使用 import Lib from 'lib'（或 require('lib')）导入 Node.js 包

  ¥Optional: use import Lib from 'lib' (or require('lib')) to import Node.js packages

Docusaurus 使我们能够以各种等效方式声明其配置，并且以下所有配置示例都会产生完全相同的结果：

¥Docusaurus gives us the ability to declare its configuration in various equivalent ways, and all the following config examples lead to the exact same result:

docusaurus.config.js

export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.nodejs.cn',
  // your site config ...
};

docusaurus.config.js

module.exports = {
  title: 'Docusaurus',
  url: 'https://docusaurus.nodejs.cn',
  // your site config ...
};

docusaurus.config.ts

import type {Config} from '@docusaurus/types';

export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.nodejs.cn',
  // your site config ...
} satisfies Config;

docusaurus.config.js

const config = {
  title: 'Docusaurus',
  url: 'https://docusaurus.nodejs.cn',
  // your site config ...
};

export default config;

docusaurus.config.js

export default function configCreator() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.nodejs.cn',
    // your site config ...
  };
}

docusaurus.config.js

export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.nodejs.cn',
    // your site config ...
  };
}

使用仅限 ESM 的软件包

使用异步配置创建器对于导入仅限 ESM 的模块（尤其是大多数 Remark 插件）非常有用。由于动态导入，可以导入此类模块：

¥Using an async config creator can be useful to import ESM-only modules (notably most Remark plugins). It is possible to import such modules thanks to dynamic imports:

docusaurus.config.js

export default async function createConfigAsync() {
  // Use a dynamic import instead of require('esm-lib')
  const lib = await import('lib');

  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.nodejs.cn',
    // rest of your site config...
  };
}

docusaurus.config.js 包含什么？

¥What goes into a docusaurus.config.js?

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

¥You should not have to write your docusaurus.config.js from scratch even if you are developing your site. All templates come with a docusaurus.config.js that includes defaults for the common options.

但是，如果你对配置的设计和实现方式有深入的了解，这会很有帮助。

¥However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented.

Docusaurus 配置的高级概述可分为：

¥The high-level overview of Docusaurus configuration can be categorized into:

• 站点元数据
• 部署配置
• 主题、插件和预设配置
• 定制配置

站点元数据

¥Site metadata

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

¥Site metadata contains the essential global metadata such as title, url, baseUrl, and favicon.

它们可用于多个地方，例如网站的标题和标题、浏览器选项卡图标、社交共享（Facebook、Twitter）信息，甚至生成提供静态文件的正确路径。

¥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.

部署配置

¥Deployment configurations

当你使用 deploy 命令部署站点时，将使用 projectName、organizationName 和可选的 deploymentBranch 等部署配置。

¥Deployment configurations such as projectName, organizationName, and optionally deploymentBranch are used when you deploy your site with the deploy command.

建议查看 部署文档 了解更多信息。

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

主题、插件和预设配置

¥Theme, plugin, and preset configurations

在 themes、plugins 和 presets 字段中分别列出你站点的 themes、plugins 和 presets。这些通常是 npm 包：

¥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

export default {
  // ...
  plugins: [
    '@docusaurus/plugin-content-blog',
    '@docusaurus/plugin-content-pages',
  ],
  themes: ['@docusaurus/theme-classic'],
};

提示

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

¥Docusaurus supports module shorthands, allowing you to simplify the above configuration as:

docusaurus.config.js

export default {
  // ...
  plugins: ['content-blog', 'content-pages'],
  themes: ['classic'],
};

它们也可以从本地目录加载：

¥They can also be loaded from local directories:

docusaurus.config.js

import path from 'path';

export default {
  // ...
  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

export default {
  // ...
  plugins: [
    [
      'content-blog',
      {
        path: 'blog',
        routeBasePath: 'blog',
        include: ['*.md', '*.mdx'],
        // ...
      },
    ],
    'content-pages',
  ],
};

要指定预设中打包的插件或主题的选项，请通过 presets 字段传递选项。在此示例中，docs 指代 @docusaurus/plugin-content-docs，theme 指代 @docusaurus/theme-classic。

¥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

export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
};

提示

presets: [['classic', {...}]] 速记也有效。

¥The presets: [['classic', {...}]] shorthand works as well.

有关配置主题、插件和预设的更多帮助，请参阅 使用插件。

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

定制配置

¥Custom configurations

Docusaurus 守护着来自未知字段的 docusaurus.config.js。要添加自定义字段，请在 customFields 中定义它们。

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

示例：

¥Example:

docusaurus.config.js

export default {
  // ...
  customFields: {
    image: '',
    keywords: [],
  },
  // ...
};

从组件访问配置

¥Accessing configuration from components

你的配置对象将可供站点的所有组件使用。你可以通过 React 上下文作为 siteConfig 访问它们。

¥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 {siteConfig} = useDocusaurusContext();
  const {title, tagline} = siteConfig;

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

提示

如果你只想在客户端使用这些字段，你可以创建自己的 JS 文件并将它们导入为 ES6 模块，无需将它们放在 docusaurus.config.js.js 中。

¥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 配置

¥Customizing Babel Configuration

对于新的 Docusaurus 项目，我们在项目根目录中自动生成了 babel.config.js。

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

babel.config.js

export default {
  presets: ['@docusaurus/core/lib/babel/preset'],
};

大多数时候，这个配置就可以正常工作。如果你想自定义 Babel 配置（例如添加对 Flow 的支持），可以直接编辑此文件。为了使更改生效，你需要重新启动 Docusaurus 开发服务器。

¥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.