版本：Canary 🚧

配置

信息

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

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

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

Syntax to declare `docusaurus.config.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

信息

The docusaurus.config.js file only supports the CommonJS module system:

Required: use module.exports = /* your config*/ to export your Docusaurus config
Optional: use require("lib") to import Node.js packages
Optional: use await import("lib") (dynamic import) in an async function to import ESM-Only Node.js packages

Node.js gives us the ability to declare our Docusaurus configuration in various equivalent ways, and all the following config examples lead to the exact same result:

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

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

module.exports = config;

docusaurus.config.js
module.exports = function configCreator() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
};

docusaurus.config.js
module.exports = async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
};

Using ESM-only packages

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
module.exports = 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...
  };
};

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

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

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

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

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

站点元数据

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

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

部署配置

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

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

主题、插件和预设配置

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

docusaurus.config.js
module.exports = {
  // ...
  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
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 模块导入，没有必要放在 docusaurus.config.js 里。

自定义 Babel 配置

我们会在新 Docusaurus 项目的根目录自动生成 babel.config.js。

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

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

配置

Syntax to declare docusaurus.config.js​

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

站点元数据​

部署配置​

主题、插件和预设配置​

自定义配置​

在组件中获取配置​

自定义 Babel 配置​