跳到主要内容
版本：3.8.1

配置

信息

请查看docusaurus.config.js API 参考，了解所有可用选项的完整列表。

Docusaurus 对配置有独到的见解。我们鼓励您将所有站点信息汇集到一处。我们对该文件中的字段进行保护，并便于在您的整个站点中访问此数据对象。

维护良好的 docusaurus.config.js 有助于您、您的协作者以及您的开源贡献者专注于文档编写，同时仍能自定义站点。

声明 docusaurus.config.js 的语法​

docusaurus.config.js 文件在 Node.js 中运行，应导出以下两者之一：

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

docusaurus.config.js 文件支持

限制

  • 必填： 使用 export default /* your config*/（或 module.exports）导出您的 Docusaurus 配置
  • 可选： 使用 import Lib from 'lib'（或 require('lib')）导入 Node.js 包

Docusaurus 允许我们以多种**等效方式**声明其配置，以下所有配置示例都会产生完全相同的结果

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.org.cn',
  // your site config ...
};
docusaurus.config.js
module.exports = {
  title: 'Docusaurus',
  url: 'https://docusaurus.org.cn',
  // your site config ...
};
docusaurus.config.ts
import type {Config} from '@docusaurus/types';

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

export default config;
docusaurus.config.js
export default function configCreator() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.org.cn',
    // your site config ...
  };
}
docusaurus.config.js
export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.org.cn',
    // your site config ...
  };
}
使用仅 ESM 的包

使用异步配置创建器可以方便地导入仅 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.org.cn',
    // rest of your site config...
  };
}

docusaurus.config.js 包含什么？​

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

然而，如果您对配置的设计和实现方式有高级别的理解，将会很有帮助。

Docusaurus 配置的高级概述可分为以下几类：

站点元数据​

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

它们在多个地方使用，例如您站点的标题和 H1 标签、浏览器标签页图标、社交分享（Facebook、X）信息，甚至用于生成提供静态文件的正确路径。

部署配置​

当您使用 deploy 命令部署站点时，会使用 `projectName`、`organizationName` 以及可选的 `deploymentBranch` 等部署配置。

建议查看部署文档以获取更多信息。

主题、插件和预设配置​

在 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 上下文以 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 转译您站点的源代码。如果您想自定义 Babel 配置，可以在项目根目录中创建 babel.config.js 文件来完成此操作。

要使用内置预设作为基本配置，请安装以下包并使用它

npm install --save @docusaurus/babel

然后，在您的 babel.config.js 文件中使用该预设

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

大多数情况下，默认的预设配置就能正常工作。如果您想自定义 Babel 配置（例如，添加对 Flow 的支持），可以直接编辑此文件。要使您的更改生效，您需要重新启动 Docusaurus 开发服务器。