跳到主要内容

配置

信息

查看 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.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 ...
  };
}
使用仅限 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.io',
    // rest of your site config...
  };
}

docusaurus.config.js 中包含什么？​

即使您正在开发站点，也不应该从头开始编写 docusaurus.config.js。所有模板都带有包含常见选项默认值的 docusaurus.config.js。

但是，如果您对配置的设计和实现方式有高层次的理解，这会很有帮助。

Docusaurus 配置的高层次概述可以分为：

站点元数据​

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

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

部署配置​

部署配置如 projectName、organizationName 和可选的 deploymentBranch 在您使用 deploy 命令部署站点时使用。

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

主题、插件和预设配置​

在 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 开发服务器。