跳到主要内容
版本：Canary 🚧

配置

信息

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

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

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

声明语法 docusaurus.config.js​

docusaurus.config.js 该文件在Node js中运行，并且应该导出以下内容:

  • 一个 配置对象
  • 一个 函数 用来创建配置对象
信息

docusaurus.config.js 文件支持：

限制条件：

  • Required: use export default /* your config*/ (or module.exports) to export your Docusaurus config
  • **可选的：**使用 import Lib from 'lib' 或者 require('lib')导入 Node.js 包

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

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // 你的站点配置...
};
docusaurus.config.js
module.exports = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // 你的站点配置……
};
docusaurus.config.ts
import type {Config} from '@docusaurus/types';

export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // 你的站点配置……
} satisfies Config;
docusaurus.config.js
const config = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // 你的站点配置……
};

export default config;
docusaurus.config.js
export default function configCreator() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // 你的站点配置……
  };
}
docusaurus.config.js
export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // 你的站点配置...
  };
}
使用仅限 ESM 的软件包

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

docusaurus.config.js
export default async function createConfigAsync() {
  // 使用动态导入来替换 require('esm-lib')
  const lib = await import('lib');

  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // 你余下的站点配置
  };
}

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

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

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

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

站点元数据​

站点元数据包括了 title、url、baseUrl、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.

部署配置​

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

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

主题、插件和预设配置​

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

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

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

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

预设中内置的插件或主题的选项需要经由 presets 字段传递。 这个例子里，docs 代表了 @docusaurus/plugin-content-docs，而 theme 代表了 @docusaurus/theme-classic。

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

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

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

自定义配置​

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

示例：

docusaurus.config.js
export default {
  // ...
  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 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 开发服务器，更改才能生效。