Version: 3.6.1

使用插件

¥Using Plugins

Docusaurus 核心不提供任何自己的功能。所有功能都委托给各个插件：文档插件提供的 docs 功能；博客插件提供的 blog 功能；或由页面插件提供的个人 pages。如果没有安装插件，该站点将不包含任何路由。

¥The Docusaurus core doesn't provide any feature of its own. All features are delegated to individual plugins: the docs feature provided by the docs plugin; the blog feature provided by the blog plugin; or individual pages provided by the pages plugin. If there are no plugins installed, the site won't contain any routes.

不过，你可能不需要一一安装常用插件：它们可以作为 preset 中的打包包进行分发。对于大多数用户来说，插件是通过预设配置来配置的。

¥You may not need to install common plugins one-by-one though: they can be distributed as a bundle in a preset. For most users, plugins are configured through the preset configuration.

我们维护了一个官方插件列表，但社区也创建了一些非官方插件。如果你想添加任何功能：自动生成文档页面、执行自定义脚本、集成其他服务...请务必查看列表：有人可能已经为你实现了！

¥We maintain a list of official plugins, but the community has also created some unofficial plugins. If you want to add any feature: autogenerating doc pages, executing custom scripts, integrating other services... be sure to check out the list: someone may have implemented it for you!

如果你感觉精力充沛，也可以阅读插件指南或插件方法参考来了解如何自己制作插件。

¥If you are feeling energetic, you can also read the plugin guide or plugin method references for how to make a plugin yourself.

安装插件

¥Installing a plugin

插件通常是一个 npm 包，因此你可以像使用 npm 来安装其他 npm 包一样安装它们。

¥A plugin is usually an npm package, so you install them like other npm packages using npm.

npm
Yarn
pnpm

npm install --save docusaurus-plugin-name

yarn add docusaurus-plugin-name

pnpm add docusaurus-plugin-name

然后将其添加到站点的 docusaurus.config.js 的 plugins 选项中：

¥Then you add it in your site's docusaurus.config.js's plugins option:

docusaurus.config.js
export default {
  // ...
  plugins: ['@docusaurus/plugin-content-pages'],
};

Docusaurus 还可以从本地目录加载插件，如下所示：

¥Docusaurus can also load plugins from your local directory, with something like the following:

docusaurus.config.js
export default {
  // ...
  plugins: ['./src/plugins/docusaurus-local-plugin'],
};

路径应该是绝对路径或相对于配置文件的路径。

¥Paths should be absolute or relative to the config file.

配置插件

¥Configuring plugins

对于插件的最基本用法，你可以仅提供插件名称或插件路径。

¥For the most basic usage of plugins, you can provide just the plugin name or the path to the plugin.

但是，插件可以通过将名称和选项对象封装在配置内的二元组中来指定选项。这种款式通常称为 "Babel 风格"。

¥However, plugins can have options specified by wrapping the name and an options object in a two-member tuple inside your config. This style is usually called "Babel Style".

docusaurus.config.js
export default {
  // ...
  plugins: [
    [
      '@docusaurus/plugin-xxx',
      {
        /* options */
      },
    ],
  ],
};

示例：

¥Example:

docusaurus.config.js
export default {
  plugins: [
    // Basic usage.
    '@docusaurus/plugin-debug',

    // With options object (babel style)
    [
      '@docusaurus/plugin-sitemap',
      {
        changefreq: 'weekly',
      },
    ],
  ],
};

多实例插件和插件 ID

¥Multi-instance plugins and plugin IDs

所有 Docusaurus 内容插件都可以支持多个插件实例。例如，拥有多个文档插件实例或多个博客可能很有用。需要为每个插件实例分配一个唯一的 ID，默认情况下，插件 ID 为 default。

¥All Docusaurus content plugins can support multiple plugin instances. For example, it may be useful to have multiple docs plugin instances or multiple blogs. It is required to assign a unique ID to each plugin instance, and by default, the plugin ID is default.

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-1',
        // other options
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-2',
        // other options
      },
    ],
  ],
};

注意

最多一个插件实例可以是 "默认插件实例"，通过省略 id 属性，或使用 id: 'default'。

¥At most one plugin instance can be the "default plugin instance", by omitting the id attribute, or using id: 'default'.

使用主题

¥Using themes

主题的加载方式与插件完全相同。从消费者的角度来看，在安装和配置插件时，themes 和 plugins 条目是可以互换的。唯一的细微差别是主题是在插件之后加载的，这对于一个主题来覆盖插件的默认主题组件是可能的。

¥Themes are loaded in the exact same way as plugins. From the consumer perspective, the themes and plugins entries are interchangeable when installing and configuring a plugin. The only nuance is that themes are loaded after plugins, and it's possible for a theme to override a plugin's default theme components.

提示

themes 和 plugins 选项会导致不同的速记决议，因此如果你想利用简写，请务必使用正确的条目！

¥The themes and plugins options lead to different shorthand resolutions, so if you want to take advantage of shorthands, be sure to use the right entry!

docusaurus.config.js
export default {
  // ...
  themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

使用预设

¥Using presets

预设是插件和主题的打包包。例如，我们没有让你在配置文件中依次注册和配置 @docusaurus/plugin-content-docs、@docusaurus/plugin-content-blog 等，而是预设了 @docusaurus/preset-classic，允许你在一个集中的位置配置它们。

¥Presets are bundles of plugins and themes. For example, instead of letting you register and configure @docusaurus/plugin-content-docs, @docusaurus/plugin-content-blog, etc. one after the other in the config file, we have @docusaurus/preset-classic preset allows you to configure them in one centralized place.

`@docusaurus/preset-classic`

经典预设默认发送到使用 create-docusaurus 创建的新 Docusaurus 网站。它包含以下主题和插件：

¥The classic preset is shipped by default to new Docusaurus websites created with create-docusaurus. It contains the following themes and plugins:

经典预设会将每个选项条目转发到相应的插件/主题。

¥The classic preset will relay each option entry to the respective plugin/theme.

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // Debug defaults to true in dev, false in prod
        debug: undefined,
        // Will be passed to @docusaurus/theme-classic.
        theme: {
          customCss: ['./src/css/custom.css'],
        },
        // Will be passed to @docusaurus/plugin-content-docs (false to disable)
        docs: {},
        // Will be passed to @docusaurus/plugin-content-blog (false to disable)
        blog: {},
        // Will be passed to @docusaurus/plugin-content-pages (false to disable)
        pages: {},
        // Will be passed to @docusaurus/plugin-sitemap (false to disable)
        sitemap: {},
        // Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified)
        gtag: {},
        // Will be passed to @docusaurus/plugin-google-tag-manager (only enabled when explicitly specified)
        googleTagManager: {},
        // DEPRECATED: Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
        googleAnalytics: {},
      },
    ],
  ],
};

安装预设

¥Installing presets

预设通常是一个 npm 包，因此你可以像使用 npm 来安装其他 npm 包一样安装它们。

¥A preset is usually an npm package, so you install them like other npm packages using npm.

npm
Yarn
pnpm

npm install --save @docusaurus/preset-classic

yarn add @docusaurus/preset-classic

pnpm add @docusaurus/preset-classic

然后，将其添加到你网站的 docusaurus.config.js 的 presets 选项中：

¥Then, add it in your site's docusaurus.config.js's presets option:

docusaurus.config.js
export default {
  // ...
  presets: ['@docusaurus/preset-classic'],
};

预设路径可以相对于配置文件：

¥Preset paths can be relative to the config file:

docusaurus.config.js
export default {
  // ...
  presets: ['./src/presets/docusaurus-local-preset'],
};

创建预设

¥Creating presets

预设是一个与插件构造函数形状相同的函数。它应该返回 { plugins: PluginConfig[], themes: PluginConfig[] } 的对象，与站点配置中接受它们的方式相同。例如，你可以指定包含以下主题和插件的预设：

¥A preset is a function with the same shape as the plugin constructor. It should return an object of { plugins: PluginConfig[], themes: PluginConfig[] }, in the same as how they are accepted in the site config. For example, you can specify a preset that includes the following themes and plugins:

src/presets/docusaurus-preset-multi-docs.js
export default function preset(context, opts = {}) {
  return {
    themes: [['docusaurus-theme-awesome', opts.theme]],
    plugins: [
      // Using three docs plugins at the same time!
      // Assigning a unique ID for each without asking the user to do it
      ['@docusaurus/plugin-content-docs', {...opts.docs1, id: 'docs1'}],
      ['@docusaurus/plugin-content-docs', {...opts.docs2, id: 'docs2'}],
      ['@docusaurus/plugin-content-docs', {...opts.docs3, id: 'docs3'}],
    ],
  };
}

然后在 Docusaurus 配置中，你可以配置预设：

¥Then in your Docusaurus config, you may configure the preset:

docusaurus.config.js
export default {
  presets: [
    [
      './src/presets/docusaurus-preset-multi-docs.js',
      {
        theme: {hello: 'world'},
        docs1: {path: '/docs'},
        docs2: {path: '/community'},
        docs3: {path: '/api'},
      },
    ],
  ],
};

这相当于执行以下操作：

¥This is equivalent of doing:

docusaurus.config.js
export default {
  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'}],
  ],
};

当某些插件和主题打算一起使用时，这尤其有用。你甚至可以将他们的选项链接在一起，例如将一个选项传递给多个插件。

¥This is especially useful when some plugins and themes are intended to be used together. You can even link their options together, e.g. pass one option to multiple plugins.

模块简写

¥Module shorthands

Docusaurus 支持插件、主题和预设的简写。当它看到插件/主题/预设名称时，它会尝试按顺序加载以下内容之一：

¥Docusaurus supports shorthands for plugins, themes, and presets. When it sees a plugin/theme/preset name, it tries to load one of the following, in that order:

[name]（如 content-docs）

¥[name] (like content-docs)
@docusaurus/[moduleType]-[name]（如 @docusaurus/plugin-content-docs）

¥@docusaurus/[moduleType]-[name] (like @docusaurus/plugin-content-docs)
docusaurus-[moduleType]-[name]（如 docusaurus-plugin-content-docs）

¥docusaurus-[moduleType]-[name] (like docusaurus-plugin-content-docs)

其中 moduleType 是 'preset'、'theme'、'plugin' 之一，具体取决于声明模块名称的字段。成功找到的第一个模块名称将被加载。

¥where moduleType is one of 'preset', 'theme', 'plugin', depending on which field the module name is declared in. The first module name that's successfully found is loaded.

如果名称是有范围的（以 @ 开头），则名称首先通过第一个斜杠分为范围和包名称：

¥If the name is scoped (beginning with @), the name is first split into scope and package name by the first slash:

@scope
^----^
 scope  (no name!)

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

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

如果没有名称（如 @jquery），则加载 [scope]/docusaurus-[moduleType]（即 @jquery/docusaurus-plugin）。否则，将尝试以下操作：

¥If there is no name (like @jquery), [scope]/docusaurus-[moduleType] (i.e. @jquery/docusaurus-plugin) is loaded. Otherwise, the following are attempted:

[scope]/[name]（如 @jquery/content-docs）

¥[scope]/[name] (like @jquery/content-docs)
[scope]/docusaurus-[moduleType]-[name]（如 @jquery/docusaurus-plugin-content-docs）

¥[scope]/docusaurus-[moduleType]-[name] (like @jquery/docusaurus-plugin-content-docs)

以下是在 plugins 字段中注册的插件的一些示例。请注意，与 ESLint 或 Babel 不同的是，ESLint 或 Babel 强制要求插件具有一致的命名约定，Docusaurus 允许更大的命名自由，因此解析不确定，但遵循上面定义的优先级。

¥Below are some examples, for a plugin registered in the plugins field. Note that unlike ESLint or Babel where a consistent naming convention for plugins is mandated, Docusaurus permits greater naming freedom, so the resolutions are not certain, but follows the priority defined above.

声明	可以解决为
`awesome`	`docusaurus-plugin-awesome`
`sitemap`	`@docusaurus/plugin-sitemap`
`@my-company`	`@my-company/docusaurus-plugin`（唯一可能的解决方案！）
`@my-company/awesome`	`@my-company/docusaurus-plugin-awesome`
`@my-company/awesome/web`	`@my-company/docusaurus-plugin-awesome/web`

安装插件​

配置插件​

多实例插件和插件 ID​

使用主题​

使用预设​

@docusaurus/preset-classic​

安装预设​

创建预设​

模块简写​