插件

插件是 Docusaurus 网站中功能的构建模块。每个插件处理其自己的独立功能。插件可以通过预设以捆绑包的形式一起工作和分发。

创建插件

插件是一个函数，它接收两个参数：context 和 options。它返回一个插件实例对象（或 Promise）。您可以创建插件作为函数或模块。有关更多信息，请参阅 插件方法参考部分。

函数定义

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

docusaurus.config.js

export default {
  // ...
  plugins: [
    async function myPlugin(context, options) {
      // ...
      return {
        name: 'my-plugin',
        async loadContent() {
          // ...
        },
        async contentLoaded({content, actions}) {
          // ...
        },
        /* other lifecycle API */
      };
    },
  ],
};

模块定义

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

docusaurus.config.js

export default {
  // ...
  plugins: [
    // without options:
    './my-plugin',
    // or with options:
    ['./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}) {
      /* ... */
    },
    /* 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

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'],
};

现在，虽然主题从插件接收相同的数据，但主题选择渲染数据的方式可能会有很大不同。

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

主题旨在完成 Docusaurus 网站的构建，并提供您的网站、插件和主题本身使用的组件。主题仍然像插件一样，并公开一些生命周期方法，但它们很可能不会使用 loadContent，因为它们只接收来自插件的数据，而不会自行生成数据；主题通常还附带一个 src/theme 目录，其中包含各种组件，这些组件通过 getThemePath 生命周期向核心公开。

总结

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