插件

插件是 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}) {
          // ...
        },
        /* 其他生命周期 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 + 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'],
};

现在，尽管主题从插件接收相同的数据，但主题选择如何将数据_渲染_为 UI 可能会有很大的不同。

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

主题旨在完成您的 Docusaurus 站点的构建，并提供由您的站点、插件和主题本身使用的组件。主题仍然像插件一样工作并公开一些生命周期方法，但最可能不会使用 loadContent，因为它们只从插件接收数据，但不生成数据；主题通常还伴随着一个充满组件的 src/theme 目录，这些组件通过 getThemePath 生命周期被核心所知。

总结：

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