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

插件

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

可用插件#

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

安装插件#

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

npm install --save docusaurus-plugin-name

然后,您需要将其添加到站点中 docusaurus.config.jsplugins 选项:

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 配置、修改加载中的数据及创建页面中使用的新组件。

插件开发#

插件可为接收两个参数的函数:contextoptions.

返回值为插件的实例对象,包括插件的生命周期 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],  ],};

Then in the folder my-plugin you can create an index.js such as this

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

context#

context 与插件无关,同一对象将传递至 Docusaurus 站点的全部插件。 The context object contains the following fields:

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

options#

options are the second optional parameter when the plugins are used. options are plugin-specific and are specified by users when they use them in docusaurus.config.js. Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes.

返回值#

The returned object value should implement the lifecycle APIs.