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

插件

插件是 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.

It returns a plugin instance object, containing plugin lifecycle APIs.

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

函数定义

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

docusaurus.config.js
module.exports = {
// ...
plugins: [
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 中指定。 另外,若预设附带了插件,则预设将提供传递至插件的正确设置。 插件开发者决定需要哪些设置。

返回值

The returned object value should implement the lifecycle APIs.