插件

¥Plugins

插件是 Docusaurus 站点中功能的构建块。每个插件都有自己独特的功能。插件可以通过预设作为打包包的一部分来运行和分发。

¥Plugins are the building blocks of features in a Docusaurus site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of a bundle via presets.

创建插件

¥Creating plugins

插件是一个带有两个参数的函数：context 和 options。它返回一个插件实例对象（或一个 promise）。你可以将插件创建为函数或模块。有关详细信息，请参阅 插件方法参考部分。

¥A plugin is a function that takes two parameters: context and options. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the plugin method references section.

函数定义

¥Function definition

你可以使用插件作为直接包含在 Docusaurus 配置文件中的函数：

¥You can use a plugin as a function directly included in the Docusaurus config file:

docusaurus.config.js

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

模块定义

¥Module definition

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

¥You can use a plugin as a module path referencing a separate file or npm package:

docusaurus.config.js

export default {
  // ...
  plugins: [
    // without options:
    './my-plugin',
    // or with options:
    ['./my-plugin', options],
  ],
};

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

¥Then in the folder my-plugin, you can create an index.js such as this:

my-plugin/index.js

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

---

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

¥You can view all plugins installed in your site using the debug plugin's metadata panel.

插件有多种类型：

¥Plugins come as several types:

• package：你安装的外部软件包

  ¥package: an external package you installed

• project：你在项目中创建的插件，作为本地文件路径提供给 Docusaurus

  ¥project: a plugin you created in your project, given to Docusaurus as a local file path

• local：使用函数定义创建的插件

  ¥local: a plugin created using the function definition

• synthetic：内部创建了 "假插件" Docusaurus，因此我们利用了模块化架构，并且不让核心执行太多特殊工作。你不会在元数据中看到它，因为它是一个实现细节。

  ¥synthetic: a "fake plugin" Docusaurus created internally, so we take advantage of our modular architecture and don't let the core do much special work. You won't see this in the metadata because it's an implementation detail.

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

¥You can access them on the client side with useDocusaurusContext().siteMetadata.pluginVersions.

插件设计

¥Plugin design

Docusaurus 插件系统的实现为我们提供了一种方便的方法来钩子网站的生命周期，以修改开发/构建期间发生的事情，其中涉及（但不限于）扩展 webpack 配置、修改加载的数据以及创建 页面中使用的新组件。

¥Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page.

主题设计

¥Theme design

当插件加载其内容时，数据将通过 createData + addRoute 或 setGlobalData 等操作提供给客户端。该数据必须序列化为纯字符串，因为 插件和主题在不同的环境中运行。一旦数据到达客户端，React 开发者就会熟悉其余的内容：数据沿着组件传递，组件与 Webpack 打包在一起，通过 ReactDOM.render 渲染到窗口...

¥When plugins have loaded their content, the data is made available to the client side through actions like createData + addRoute or setGlobalData. This data has to be serialized to plain strings, because plugins and themes run in different environments. Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through ReactDOM.render...

主题提供一组 UI 组件来渲染内容。大多数内容插件需要与主题配对才能真正有用。UI 是与数据模式分开的层，这使得交换设计变得容易。

¥Themes provide the set of UI components to render the content. Most content plugins need to be paired with a theme in order to be actually useful. The UI is a separate layer from the data schema, which makes swapping designs easy.

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

¥For example, a Docusaurus blog may consist of a blog plugin and a blog theme.

注意

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

¥This is a contrived example: in practice, @docusaurus/theme-classic provides the theme for docs, blog, and layouts.

docusaurus.config.js

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

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

¥And if you want to use Bootstrap styling, you can swap out the theme with theme-blog-bootstrap (another fictitious non-existing theme):

docusaurus.config.js

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

现在，尽管主题从插件接收相同的数据，但主题选择将数据渲染为 UI 的方式可能截然不同。

¥Now, although the theme receives the same data from the plugin, how the theme chooses to render the data as UI can be drastically different.

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

¥While themes share the exact same lifecycle methods with plugins, themes' implementations can look very different from those of plugins based on themes' designed objectives.

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

¥Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. A theme still acts like a plugin and exposes some lifecycle methods, but most likely they would not use loadContent, since they only receive data from plugins, but don't generate data themselves; themes are typically also accompanied by an src/theme directory full of components, which are made known to the core through the getThemePath lifecycle.

总结一下：

¥To summarize:

• 主题与插件共享相同的生命周期方法

  ¥Themes share the same lifecycle methods with Plugins

• 主题在所有现有插件之后运行

  ¥Themes are run after all existing Plugins

• 主题通过提供 getThemePath 来添加组件别名。

  ¥Themes add component aliases by providing getThemePath.