跳到主要内容
版本：Canary 🚧

配置

信息

请查看 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',
  // 你的站点配置...
};
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 等重要全局元数据。

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

部署配置​

使用 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 默认使用 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 开发服务器，更改才能生效。