插件

插件是 Docusaurus 2 网站功能的基本构件模块。每个插件都具有独立的功能。插件可以通过 预设 起作用并发布。

可用的插件

这是 官方插件列表。还有由社区创建的 非官方插件。

安装插件

插件通常是 npm 软件包，因此你可以像其他 npm 软件包一样使用 npm 安装它们。

• npm
• Yarn

npm install --save docusaurus-plugin-name

yarn add docusaurus-plugin-name

然后将其添加到站点的 docusaurus.config.js 配置文件中的 plugins 配置项中：

docusaurus.config.js

module.exports = {
  // ...
  plugins: ['@docusaurus/plugin-content-pages'],

};

Docusaurus 也可以从本地目录加载插件，你可以执行以下操作：

docusaurus.config.js

const path = require('path');
module.exports = {
  // ...
  plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],

};

配置插件

对于最基本的插件用法，你可以仅提供插件名称或插件的绝对路径。

但是，还可以通过将插件名及其参数对象组合成一个数组的并添加到配置文件中的 plugins 配置项中。这种风格通常称为 Babel 风格。

docusaurus.config.js

module.exports = {
  // ...
  plugins: [
    [

'@docusaurus/plugin-xxx', { /* 参数对象 */ }, ], ], };

示例：

docusaurus.config.js

module.exports = {
  plugins: [
    // 基本用法。
    '@docusaurus/plugin-google-analytics',
    // 带有参数对象的用法（即 babel 风格）
    [
      '@docusaurus/plugin-sitemap',
      {
        changefreq: 'weekly',
      },
    ],
  ],
};

插件的多个实例以及 id

所有 Docusaurus 的内容插件都支持配置为多个实例。

文档插件（即 plugin-content-docs）支持 额外的多实例文档

需要为插件的每个实例分配一个唯一的 id。

插件实例的 id 默认为 default。

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-xxx',
      {
        id: 'plugin-xxx-1',

// other options }, ], [ '@docusaurus/plugin-xxx', { id: 'plugin-xxx-2', // other options }, ], ], };

note

一个插件最多只有一个实例作为“插件的默认实例”，此默认实例可以通过省略 id 属性或使用 id: 'default' 来设置。

插件的设计

Docusaurus 插件系统的实现方式为我们提供了一种便捷的途径可以参与进网站的生命周期中，以修改开发/构建过程中发生的事情，这涉及（但不限于）扩展 webpack 配置、修改要加载的数据以及创建在新的页面中所使用的组件。

创建插件

插件是一个模块，该模块导出（export）了一个可以接受两个参数的函数，并在执行后返回一个对象。

模块定义

插件所导出（export）的模块在调用时被传入两个参数：context 和 options，并返回一个实现了 生命周期 API 的 JavaScript 对象。

例如，如果你在 docusaurus.config.js 文件中引用了像下面这样的本地文件夹：

docusaurus.config.js

module.exports = {
  // ...
  plugins: [path.resolve(__dirname, 'my-plugin')],
};

那么，在 my-plugin 文件夹中你就可以创建一个类似下面这样的 index.js 文件

index.js

module.exports = function (context, options) {
  // ...
  return {
    name: 'my-docusaurus-plugin',
    async loadContent() {
      /* ... */
    },
    async contentLoaded({content, actions}) {
      /* ... */
    },
    /* other lifecycle API */
  };
};

my-plugin 文件夹也可以是一个完整的软件包，该软件包拥有自己的 package.json 和 src/index.js 文件

context

context 对象是与插件无关的，并且该对象会被传递到 Docusaurus 站点所用到的所有插件中。context 对象包含以下字段：

interface LoadContext {
  siteDir: string;
  generatedFilesDir: string;
  siteConfig: DocusaurusConfig;
  outDir: string;
  baseUrl: string;
}

options

options 是 插件被使用时所接受到的第二个参数（可选）。options 是特定于插件的，当插件被用户使用时，由用户在 docusaurus.config.js 文件中设置。或者，如果预设（preset）中包含插件，则预设（preset）将负责向插件传递正确的 options。插件接受什么样的 options 由插件自己决定。

返回值

返回的对象需要实现 生命周期 API。