版本：Canary 🚧

使用插件

**Docusaurus 核心不提供它自己的任何功能。**所有功能都委托给了独立插件：文档功能由文档插件提供；博客功能由博客插件提供；独立页面由页面插件提供。如果没有安装插件，站点就不会包含任何路径。

但是，你可能不需要一个一个地安装常用插件：它们可以作为预设的一部分被打包分发。对于大多数用户来说，插件是通过预设选项来配置的。

我们有一份官方插件列表，而社区也开发了一些非官方插件。如果你想要添加任何功能：自动生成文档页面、执行自定义脚本、整合其他服务……记得翻翻那个列表：有人可能已经帮你实现好了！

如果你觉得自己很有精力，你也可以阅读插件指南或插件方法总览了解如何自己制作插件。

安装插件

插件通常为 npm 软件包，所以你可以像其他 npm 包一样安装。

npm
Yarn
pnpm

npm install --save docusaurus-plugin-name

yarn add docusaurus-plugin-name

pnpm add docusaurus-plugin-name

然后，你需要把它添加到站点 docusaurus.config.js 的 plugins 选项：

docusaurus.config.js
export default {
  // ...
  plugins: ['@docusaurus/plugin-content-pages'],
};

Docusaurus 也可以从你的本地目录加载插件，只需要像这样填写：

docusaurus.config.js
export default {
  // ...
  plugins: ['./src/plugins/docusaurus-local-plugin'],
};

路径需要是绝对的，或者相对于配置文件。

配置插件

最简单的插件用法就是提供插件名称或插件路径。

如果要声明选项，需要在配置里把名称和配置对象放在一个二元组中。这种风格通常被称作 Babel 风格。

docusaurus.config.js
export default {
  // ...
  plugins: [
    [
      '@docusaurus/plugin-xxx',
      {
        /* 选项 */
      },
    ],
  ],
};

示例：

docusaurus.config.js
export default {
  plugins: [
    // 基础用法
    '@docusaurus/plugin-debug',

    // 包含选项对象（Babel 风格）
    [
      '@docusaurus/plugin-sitemap',
      {
        changefreq: 'weekly',
      },
    ],
  ],
};

多实例插件及插件 ID

所有的 Docusaurus 内容插件都可支持多个插件实例。比如，可以有多个文档插件实例或多个博客。每个插件实例都需要分配一个唯一的 ID。插件 ID 默认为 default。

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-1',
        // 其它可选项
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-2',
        // 其它可选项
      },
    ],
  ],
};

备注

最多可以有一个插件实例被作为「默认实例」。你可以通过省略 id 属性或使用 id: 'default' 来将其设为默认。

使用主题

主题和插件的加载方式完全相同。从使用者的角度，themes 和 plugins 字段在安装和配置插件时可以互换。唯一的细微差别是主题会在插件之后加载，并且主题可以覆盖插件的默认主题组件。

提示

themes 和 plugins 选项会导致不同的简写解析模式，所以如果你想要利用简写，请务必使用正确的选项！

docusaurus.config.js
export default {
  // ...
  themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

使用预设

预设是插件及主题的合集。比如，你不一定需要在配置文件中挨个注册并配置 @docusaurus/plugin-content-docs、@docusaurus/plugin-content-blog 等插件。我们提供了 @docusaurus/preset-classic 预设，允许你在一个地方集中配置它们。

`@docusaurus/preset-classic`

用 create-docusaurus 新建的 Docusaurus 网站默认自带经典预设。它包含了下列主题和插件：

经典预设会把每个配置项目转发给相应的插件/主题。

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // debug 在开发环境中默认为 true，而在生产环境中为 false
        debug: undefined,
        // 会被传递给 @docusaurus/theme-classic。
        theme: {
          customCss: ['./src/css/custom.css'],
        },
        // 会被传递给 @docusaurus/plugin-content-docs（使用 false 来禁用）
        docs: {},
        // 会被传递给 @docusaurus/plugin-content-blog（使用 false 来禁用）
        blog: {},
        // 会被传递给 @docusaurus/plugin-content-pages（使用 false 来禁用）
        pages: {},
        // 会被传递给 @docusaurus/plugin-sitemap（使用 false 来禁用）
        sitemap: {},
        // 会被传递给 @docusaurus/plugin-google-gtag（只在显示声明时才会被启用）
        gtag: {},
        // 会被传递给 @docusaurus/plugin-google-tag-manager（只在显示声明时才会被启用）
        googleTagManager: {},
        // 已废弃：会被传递给 @docusaurus/plugin-google-analytics（只在显示声明时才会被启用）
        googleAnalytics: {},
      },
    ],
  ],
};

安装预设

预设通常是一个 npm 包，所以你可以像其他包一样通过 npm 安装。

npm
Yarn
pnpm

npm install --save @docusaurus/preset-classic

yarn add @docusaurus/preset-classic

pnpm add @docusaurus/preset-classic

然后，将其添加到网站的 docusaurus.config.js 中的 presets 选项：

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

预设路径可以是相对于配置文件的:

docusaurus.config.js
export default {
  // ...
  presets: ['./src/presets/docusaurus-local-preset'],
};

新建预设

预设是一个结构与插件构造函数相同的函数。它应该返回一个对象，形如 { plugins: PluginConfig[], themes: PluginConfig[] }，与网站配置所接受的格式相同。举个例子，你可以定义一个包含下列主题及插件的预设：

src/presets/docusaurus-preset-multi-docs.js
export default function preset(context, opts = {}) {
  return {
    themes: [['docusaurus-theme-awesome', opts.theme]],
    plugins: [
      // 同时使用三个文档插件！
      // 给每个插件分配一个 ID，这样用户就不需要分配 ID 了
      ['@docusaurus/plugin-content-docs', {...opts.docs1, id: 'docs1'}],
      ['@docusaurus/plugin-content-docs', {...opts.docs2, id: 'docs2'}],
      ['@docusaurus/plugin-content-docs', {...opts.docs3, id: 'docs3'}],
    ],
  };
}

然后在你的 Docusaurus 配置中，你可以转而设置使用上文所述的预设：

docusaurus.config.js
export default {
  presets: [
    [
      './src/presets/docusaurus-preset-multi-docs.js',
      {
        theme: {hello: 'world'},
        docs1: {path: '/docs'},
        docs2: {path: '/community'},
        docs3: {path: '/api'},
      },
    ],
  ],
};

这与下列配置等同：

docusaurus.config.js
export default {
  themes: [['docusaurus-theme-awesome', {hello: 'world'}]],
  plugins: [
    ['@docusaurus/plugin-content-docs', {id: 'docs1', path: '/docs'}],
    ['@docusaurus/plugin-content-docs', {id: 'docs2', path: '/community'}],
    ['@docusaurus/plugin-content-docs', {id: 'docs3', path: '/api'}],
  ],
};

此方法非常适合需要整合某些插件及主题的情况。你甚至可以把它们的选项关联在一起，比如把一个选项传递给多个插件。

模块简写

Docusaurus 支持插件、主题和预设的名称简写。当它看到一个插件/主题/预设名称时，它会试图按照以下顺序加载其中一个：

[名字]（比如 content-docs）
@docusaurus/[模块类别]-[名字]（比如 @docusaurus/plugin-content-docs）
docusaurus-[模块类别]-[名字]（比如 docusaurus-plugin-content-docs）

其中模块类型是 'preset'、'theme'、'plugin' 中的一种，取决于模块名称位于哪个字段中。第一个找到的模块会被加载。

如果名称包含前缀（以 @开头），名称会被首先按第一个斜杠分割成前缀和包名：

@scope
^----^
 前缀（没有名称！）

@scope/awesome
^----^ ^-----^
 前缀    名称

@scope/awesome/main
^----^ ^----------^
 前缀       名称

如果没有名称（比如 @jquery），那么会加载 [前缀]/docusaurus-[模块类别]（即 @jquery/docusaurus-plugin）。否则，会尝试下列名称：

[前缀]/[名字]（比如 @jquery/content-docs）
[前缀]/docusaurus-[模块类别]-[名字]（比如 @jquery/docusaurus-plugin-content-docs）

下面是一些示例，假设有一个在 plugins 字段注册的插件。请注意，ESLint 和 Babel 有对插件的统一命名规范要求，但 Docusaurus 允许更大的命名自由度，所以解析不是唯一的，而是遵循上面定义的优先次序。

声明	可能被解析成
`awesome`	`docusaurus-plugin-awesome`
`sitemap`	`@docusaurus/plugin-sitemap`
`@my-company`	`@my-company/docusaurus-plugin`（解析是唯一的！）
`@my-company/awesome`	`@my-company/docusaurus-plugin-awesome`
`@my-company/awesome/web`	`@my-company/docusaurus-plugin-awesome/web`

安装插件​

配置插件​

多实例插件及插件 ID​

使用主题​

使用预设​

@docusaurus/preset-classic​

安装预设​

新建预设​

模块简写​