跳到主要内容

插件

插件是 Docusaurus 站点功能的构建块。每个插件都处理其自身的功能。插件可以通过预设作为捆绑包的一部分工作和分发。

创建插件

插件是一个函数,它接受两个参数:contextoptions。它返回一个插件实例对象(或一个 promise)。您可以将插件创建为函数或模块。有关更多信息,请参阅 插件方法参考部分

函数定义

您可以直接将插件用作包含在 Docusaurus 配置文件中的函数:

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

模块定义

您可以将插件用作模块路径,引用单独的文件或 npm 包:

docusaurus.config.js
export default {
// ...
plugins: [
// 无选项:
'./my-plugin',
// 或带选项:
['./my-plugin', options],
],
};

然后在 my-plugin 文件夹中,您可以创建一个类似这样的 index.js

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

您可以使用 调试插件的元数据面板 查看站点中安装的所有插件。

插件有几种类型:

  • package:您安装的外部包
  • project:您在项目中创建的插件,作为本地文件路径提供给 Docusaurus
  • local:使用函数定义创建的插件
  • synthetic:Docusaurus 在内部创建的“伪插件”,因此我们利用了模块化架构,并且不会让核心做太多特殊的工作。您在元数据中看不到它,因为它是一个实现细节。

您可以使用 useDocusaurusContext().siteMetadata.pluginVersions 在客户端访问它们。

插件设计

Docusaurus 对插件系统的实现为我们提供了一种便捷的方式来连接到网站的生命周期,以修改开发/构建过程中发生的事情,这包括(但不限于)扩展 webpack 配置、修改加载的数据以及创建要在页面中使用的新组件。

主题设计

当插件加载了它们的内容后,数据通过诸如 createData + addRoutesetGlobalData 之类的操作提供给客户端。此数据必须被_序列化_为纯字符串,因为 插件和主题在不同的环境中运行 。一旦数据到达客户端,其余部分对于 React 开发人员来说就变得熟悉了:数据沿着组件传递,组件与 Webpack 捆绑在一起,并通过 ReactDOM.render 呈现到窗口……

**主题提供用于呈现内容的 UI 组件集。**大多数内容插件需要与主题配对才能真正有用。UI 是与数据模式分开的层,这使得交换设计变得容易。

例如,Docusaurus 博客可能由博客插件和博客主题组成。

备注

这是一个人为的例子:实际上,@docusaurus/theme-classic 提供了文档、博客和布局的主题。

docusaurus.config.js
export default {
themes: ['theme-blog'],
plugins: ['plugin-content-blog'],
};

如果您想使用 Bootstrap 样式,您可以使用 theme-blog-bootstrap(另一个虚构的非现有主题)替换主题:

docusaurus.config.js
export default {
themes: ['theme-blog-bootstrap'],
plugins: ['plugin-content-blog'],
};

现在,尽管主题从插件接收相同的数据,但主题选择如何将数据_呈现_为 UI 的方式可能大相径庭。

虽然主题与插件共享完全相同生命周期方法,但基于主题的设计目标,主题的实现可能与插件的实现看起来非常不同。

主题旨在完成 Docusaurus 站点的构建,并提供站点、插件和主题本身使用的组件。主题仍然像插件一样运行并公开一些生命周期方法,但它们很可能不会使用 loadContent ,因为它们只接收来自插件的数据,而不会自己生成数据;主题通常还带有包含组件的 src/theme 目录,这些组件通过 getThemePath 生命周期让核心知道。

总而言之:

  • 主题与插件共享相同生命周期方法
  • 主题在所有现有插件之后运行
  • 主题通过提供 getThemePath 添加组件别名。