跳到主要内容
版本：3.6.0

配置

信息

请查看docusaurus.config.js API reference，以获取详尽的选项列表。

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

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 文件在 Node.js 中运行，并且应该导出以下之一：

  • 一个 配置对象（config object）
  • 一个创建配置对象的 函数（function）
信息

The docusaurus.config.js file supports:

限制条件：

  • Required: use export default /* your config*/ (or module.exports) to export your Docusaurus config
  • Optional: use import Lib from 'lib' (or require('lib')) to import Node.js packages

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.io',
  // your site config ...
};
docusaurus.config.js
module.exports = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};
docusaurus.config.ts
import type {Config} from '@docusaurus/types';

export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
} satisfies Config;
docusaurus.config.js
const config = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};

export default config;
docusaurus.config.js
export default function configCreator() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
}
docusaurus.config.js
export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
}
Using ESM-only packages

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

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.io',
    // rest of your site config...
  };
}

What goes into a 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.

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

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

Site metadata​

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, X) information or even to generate the correct path to serve your static files.

Deployment configurations​

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​

List the themes, plugins, and presets for your site in the themes, plugins, and presets fields, respectively. 这些通常为 npm 软件包：

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

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

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

这些模块也可以从本地目录加载：

docusaurus.config.js
import path from 'path';

export default {
  // ...
  themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};

要指定插件或主题选项，请将配置文件的插件或主题名称替换一个二元组，包含了名称及配置选项对象：

docusaurus.config.js
export default {
  // ...
  plugins: [
    [
      'content-blog',
      {
        path: 'blog',
        routeBasePath: 'blog',
        include: ['*.md', '*.mdx'],
        // ...
      },
    ],
    '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
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
};
提示

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

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

Custom configurations​

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

示例：

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

Accessing configuration from components​

站点中的所有组件都可以访问配置对象。 And you may access them via React context as siteConfig.

简单示例：

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

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

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

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​

Docusaurus transpiles your site's source code using Babel by default. If you want to customize the Babel configuration, you can do so by creating a babel.config.js file in your project root.

To use the built-in preset as a base configuration, install the following package and use it

npm install --save @docusaurus/theme-live-codeblock

Then use the preset in your babel.config.js file:

babel.config.js
export default {
  presets: ['@docusaurus/babel/preset'],
};

Most of the time, the default preset configuration will work just fine. 如果你想要自定义你的 Babel 配置（比如添加 Flow 支持），你可以直接编辑这个文件。 你需要重新启动 Docusaurus 开发服务器，更改才能生效。