跳转至主内容
Version: 2.0.0-beta.5 🚧

插件

插件是 Docusaurus 2 功能特性的基石。 每个插件都有其自己的独立功能。 插件可打包在预设中进行分发。

可用插件#

我们有一份官方插件列表，而社群也开发了一些非官方插件。

安装插件#

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

npm install --save 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')],};

配置插件#

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

但是，插件可能需要包裹名称及设置对象来指定选项。 这种风格通常称作 Babel Style。

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

示例：

docusaurus.config.js
module.exports = {  plugins: [    // 基础用法    '@docusaurus/plugin-google-analytics',
    // 携带设置对象（babel style）    [      '@docusaurus/plugin-sitemap',      {        changefreq: 'weekly',      },    ],  ],};

多实例插件及插件 ID#

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

文档插件则有额外的多实例文档。

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

默认情况下，插件 ID 为 default。

docusaurus.config.js
module.exports = {  plugins: [    [      '@docusaurus/plugin-xxx',      {        id: 'plugin-xxx-1',        // 其他设置      },    ],    [      '@docusaurus/plugin-xxx',      {        id: 'plugin-xxx-2',        // 其他设置      },    ],  ],};
note

仅有一个插件实例可作为 "默认插件实例"。您可缺省 id 属性或使用 id: 'default' 来将其设为默认。

插件设计#

Docusaurus 的插件系统实现可让您轻松 Hook 进网站的生命周期来更改开发/构建时的行为，包括但不限于扩展 Webpack 配置、修改加载中的数据及创建页面中使用的新组件。

插件开发#

插件可为接收两个参数的函数：context 及 options.

返回值为插件的实例对象，包括插件的生命周期 API。

您可将其定义为函数或模块。

函数定义#

您可将插件作为函数，直接声明于 Docusaurus 的配置文件中：

docusaurus.config.js
module.exports = {  // ...  plugins: [    // highligh-start    function myPlugin(context, options) {      // ...      return {        name: 'my-plugin',        async loadContent() {          // ...        },        async contentLoaded({content, actions}) {          // ...        },        /* 其他生命周期 API */      };    },  ],};

模块定义#

您也可将插件作为模块，并从其他文件或 NPM 软件包中进行加载：

docusaurus.config.js
module.exports = {  // ...  plugins: [    // 不带选项：    './my-plugin',    // 或者带上选项：    ['./my-plugin', options],  ],};

随后，您可在 my-plugin 文件夹中，创建内容类似如下的 index.js

my-plugin.js
module.exports = function myPlugin(context, options) {  // ...  return {    name: 'my-plugin',    async loadContent() {      /* ... */    },    async contentLoaded({content, actions}) {      /* ... */    },    /* 其他生命周期 API */  };};

context#

context 与插件无关，同一对象将传递至 Docusaurus 站点的全部插件。 context 对象含有以下字段：

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

options#

options 是插件的第二个可选参数。 options 为每个插件的独立参数，由用户在 docusaurus.config.js 中指定。 另外，若预设附带了插件，则预设将提供传递至插件的正确设置。 插件开发者决定需要哪些设置。

返回值#

返回的对象值应实现生命周期 API。