版本：Canary 🚧

插件

插件是 Docusaurus 2 站点功能的构建模块。每个插件都有自己的特性。插件可以通过预设作为捆绑包的一部分工作和分发。

创建插件

插件是一个带有两个参数的函数:context和options。它返回一个插件实例对象(或一个 promise)。您可以将插件创建为函数或模块。要了解更多信息，请参考插件方法参考部分。

函数定义

你可以将插件作为一个函数直接包含在 Docusaurus 配置文件中:

docusaurus.config.js
module.exports = {
  // ...
  plugins: [
    async function myPlugin(context, options) {
      // ...
      return {
        name: "my-plugin",
        async loadContent() {
          // ...
        },
        async contentLoaded({ content, actions }) {
          // ...
        },
        /* other lifecycle API */
      };
    },
  ],
};

模块定义

你可以使用插件作为模块路径，引用一个单独的文件或 npm 包:

docusaurus.config.js
module.exports = {
  // ...
  plugins: [
    // without options:
    "./my-plugin",
    // or with options:
    ["./my-plugin", options],
  ],
};

然后在my-plugin文件夹中，你可以创建一个index.js，如下所示:

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

你可以使用调试插件的元数据面板查看所有安装在你网站上的插件。

插件有几种类型:

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

你可以通过useDocusaurusContext().siteMetadata.pluginVersions在客户端访问它们。

插件的设计

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

主题设计

当插件加载它们的内容时，数据通过createData + addRoute或setGlobalData等操作提供给客户端。这些数据必须被序列化为普通字符串，因为插件和主题在不同的环境中运行。一旦数据到达客户端，剩下的部分对 React 开发者来说就很熟悉了:数据通过组件传递，组件与 Webpack 捆绑在一起，并通过ReactDOM.render渲染到窗口……

主题提供了一组 UI 组件来呈现内容。 大多数内容插件需要与主题配对才能真正有用。UI 是一个独立于数据模式的层，这使得交换设计变得容易。

例如，Docusaurus 博客可能包含一个博客插件和一个博客主题。

备注

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

docusaurus.config.js
module.exports = {
  themes: ["theme-blog"],
  plugins: ["plugin-content-blog"],
};

如果你想使用 Bootstrap 样式，你可以用theme-blog-bootstrap(另一个虚构的不存在的主题)替换主题:

docusaurus.config.js
module.exports = {
  themes: ["theme-blog-bootstrap"],
  plugins: ["plugin-content-blog"],
};

现在，虽然主题从插件接收相同的数据，但主题如何选择render数据作为 UI 可能会有很大的不同。

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

主题旨在完成 Docusaurus 站点的构建，并提供站点、插件和主题本身使用的组件。主题仍然像插件一样，暴露了一些生命周期方法，但最有可能的是他们不会使用loadContent，因为他们只从插件接收数据，但不生成数据自己;主题通常也伴随着一个充满组件的src/theme目录，这些组件通过getThemePath生命周期为核心所知。总结:

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

插件

创建插件​

函数定义​

模块定义​

插件的设计​

主题设计​

创建插件

函数定义

模块定义

插件的设计

主题设计