第20章 使用插件 (Using Plugins)

版本：2.x使用插件 Docusaurus 核心本身不提供任何功能，所有功能都由独立的插件实现：docs 功能由 docs 插件提供，blog 功能由 blog 插件提供，单独的页面则由 pages 插件提供。如果没有安装任何插件，站点就不会有任何路由。 不过，常用插件通常不必逐个安装：它们可以打包成 preset 一起分发。对大多数用户来说，插件都是通过 preset 配置来使用的。 我们维护了一份官方插件列表，社区也开发了不少非官方插件。如果你想添加某个功能，比如自动生成文档页面、执行自定义脚本、集成其他服务等，不妨先查一下这份列表——说不定已经有人替你实现了！ 如果你有兴致，也可以阅读插件指南或插件方法参考文档，自己动手写一个插件。 安装插件 插件通常是一个 npm 包，所以可以用 npm 像安装其他 npm 包一样安装它。 npm install --save docusaurus-plugin-name
yarn add docusaurus-plugin-name
pnpm add docusaurus-plugin-name
bun add docusaurus-plugin-name
然后在站点的 docusaurus.config.js 的 plugins 选项中添加它： docusaurus.config.jsmodule.exports = {
// ...
plugins: ['@docusaurus/plugin-content-pages'],
};
Docusaurus 也支持从本地目录加载插件，例如： docusaurus.config.jsmodule.exports = {
// ...
plugins: ['./src/plugins/docusaurus-local-plugin'],
};
路径可以是绝对路径，也可以是相对于配置文件的路径。 配置插件 最简单的用法是只提供插件名称或插件路径。 不过插件也可以接收配置项：在配置中用二元数组把插件名和选项对象包起来。这种写法通常称为“Babel 风格”。 docusaurus.config.jsmodule.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-xxx',
{
/* options */
},
],
],
};
示例： docusaurus.config.jsmodule.exports = {
plugins: [
// 基本用法。
'@docusaurus/plugin-debug',

// 带配置项对象（babel 风格）
[
'@docusaurus/plugin-sitemap',
{
changefreq: 'weekly',
},
],
],
};
多实例插件与插件 ID 所有 Docusaurus 内容插件均支持多实例。例如，你可能需要配置多个 docs 插件实例或多个博客。每个插件实例必须分配一个唯一的 ID，默认情况下，该 ID 为 default。 `docusaurus.config.js` ``` module.exports = { plugins: [ [ '@docusaurus/plugin-content-docs', { id: 'docs-1', // 其他选项 }, ], [ '@docusaurus/plugin-content-docs', { id: 'docs-2', // 其他选项 }, ], ], }; ``` > 注意 最多只能有一个插件实例作为“默认插件实例”，可以通过省略 id 属性或设置 `id: 'default'` 来实现。 使用主题 主题的加载方式与插件完全相同。从使用者角度看，在安装和配置插件时，themes 和 plugins 条目是可以互换的。唯一的细微区别在于：主题在插件之后加载，因此主题可以覆盖插件的默认主题组件。 > 提示 themes 和 plugins 选项导致不同的简写解析结果，因此如果你想利用简写功能，务必使用正确的条目！ `docusaurus.config.js` ``` module.exports = { // ... themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'], }; ``` 使用预设 预设（Presets）是插件和主题的集合包。例如，与其在配置文件中逐个注册和配置 `@docusaurus/plugin-content-docs`、`@docusaurus/plugin-content-blog` 等，`@docusaurus/preset-classic` 预设允许你在一个中心化的位置进行配置。 `@docusaurus/preset-classic` 经典预设默认应用于通过 create-docusaurus 创建的新 Docusaurus 网站。它包含以下主题和插件： - `@docusaurus/theme-classic` - `@docusaurus/theme-search-algolia` - `@docusaurus/plugin-content-docs` - `@docusaurus/plugin-content-blog` - `@docusaurus/plugin-content-pages` - `@docusaurus/plugin-debug` - `@docusaurus/plugin-google-gtag` - `@docusaurus/plugin-google-tag-manager` - `@docusaurus/plugin-google-analytics`（已弃用） - `@docusaurus/plugin-sitemap` 经典预设会将每个选项条目传递给相应的插件/主题。 `docusaurus.config.js` ``` module.exports = { presets: [ [ '@docusaurus/preset-classic', { // Debug 在开发环境默认为 true，在生产环境默认为 false 安装预设 预设通常是一个 npm 包，你像安装其他 npm 包一样安装它们： npmYarnpnpmBunnpm install --save @docusaurus/preset-classic
yarn add @docusaurus/preset-classic
pnpm add @docusaurus/preset-classic
bun add @docusaurus/preset-classic
然后在 docusaurus.config.js 的 presets 选项中添加它： docusaurus.config.jsmodule.exports = {
// ...
presets: ['@docusaurus/preset-classic'],
};
预设路径相对于配置文件解析： docusaurus.config.jsmodule.exports = {
// ...
presets: ['./src/presets/docusaurus-local-preset'],
};
创建预设 预设是一个与 Plugin 构造函数结构一致的函数，它应返回一个包含 { plugins: PluginConfig[], themes: PluginConfig[] } 的对象，用法与在站点配置中加载它们的方式相同。示例：一个包含多个主题和 Plugin 的预设： src/presets/docusaurus-preset-multi-docs.jsmodule.exports = function preset(context, opts = {}) {
return {
themes: [['docusaurus-theme-awesome', opts.theme]],
plugins: [
// 同时使用三个文档 Plugin！
// 自动分配唯一 ID，无需用户手动指定
['@docusaurus/plugin-content-docs', {...opts.docs1, id: 'docs1'}],
['@docusaurus/plugin-content-docs', {...opts.docs2, id: 'docs2'}],
然后，在 Docusaurus 配置文件中配置这个 preset 即可： docusaurus.config.jsmodule.exports = {
presets: [
[
'./src/presets/docusaurus-preset-multi-docs.js',
{
theme: {hello: 'world'},
docs1: {path: '/docs'},
docs2: {path: '/community'},
docs3: {path: '/api'},
},
],
],
};
这样写等价于： docusaurus.config.jsmodule.exports = {
themes: [['docusaurus-theme-awesome', {hello: 'world'}]],
plugins: [
['@docusaurus/plugin-content-docs', {id: 'docs1', path: '/docs'}],
['@docusaurus/plugin-content-docs', {id: 'docs2', path: '/community'}],
['@docusaurus/plugin-content-docs', {id: 'docs3', path: '/api'}],
],
};
当多个插件和主题需要搭配使用时，这种方式特别方便。你甚至可以把它们的选项关联起来，比如把一个选项传给多个插件。 模块简写​ Docusaurus 为 plugins、themes 和 presets 支持简写形式。遇到一个 plugin/theme/preset 名称时，它会按以下顺序尝试加载： - [name]（如 content-docs） - @docusaurus/[moduleType]-[name]（如 @docusaurus/plugin-content-docs） - docusaurus-[moduleType]-[name]（如 docusaurus-plugin-content-docs） 其中 moduleType 取值为 'preset'、'theme' 或 'plugin'，取决于模块名声明在哪个字段里。第一个成功找到的模块名会被加载。 如果名称带有作用域（以 @ 开头），会先按第一个斜杠拆分为 scope 和包名： @scope
^----^
scope (no name!)

@scope/awesome
^----^ ^-----^
scope name

@scope/awesome/main
^----^ ^----------^
scope name
若未提供名称（例如 @jquery），则加载 [scope]/docusaurus-[moduleType]（即 @jquery/docusaurus-plugin）。若提供了名称，则按以下顺序尝试解析： [scope]/[name]（例如 @jquery/content-docs） [scope]/docusaurus-[moduleType]-[name]（例如 @jquery/docusaurus-plugin-content-docs） 以下是 plugins 字段中注册插件的一些示例。请注意，与 ESLint 或 Babel 强制要求插件命名规范不同，Docusaurus 允许更灵活的命名，因此解析结果并不唯一，但遵循上述优先级定义。 Declaration | May be resolved as awesome | docusaurus-plugin-awesome, sitemap @docusaurus/plugin-sitemap | @my-company @my-company | @my-company/docusaurus-plugin (唯一可能的解析结果) @my-company/awesome | @my-company/docusaurus-plugin-awesome @my-company/awesome/web | @my-company/docusaurus-plugin-awesome/web