跳到主要内容
版本：3.0.1

使用插件

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. 如果没有安装插件，站点就不会包含任何路径。

You may not need to install common plugins one-by-one though: they can be distributed as a bundle in a preset. 对于大多数用户来说，插件是通过预设选项来配置的。

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 install --save docusaurus-plugin-name

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.config.js
export default {
  // ...
  plugins: ['./src/plugins/docusaurus-local-plugin'],
};

路径需要是绝对的，或者相对于配置文件。

Configuring plugins​

最简单的插件用法就是提供插件名称或插件路径。

如果要声明选项，需要在配置里把名称和配置对象放在一个二元组中。 这种风格通常被称作 Babel 风格。

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

示例：

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

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

Multi-instance plugins and plugin IDs​

所有的 Docusaurus 内容插件都可支持多个插件实例。 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',
        // 其它可选项
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-2',
        // 其它可选项
      },
    ],
  ],
};
备注

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

Using themes​

主题和插件的加载方式完全相同。 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.

提示

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​

预设是插件及主题的合集。 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​

The classic preset is shipped by default to new Docusaurus websites created with create-docusaurus. 它包含了下列主题和插件：

经典预设会把每个配置项目转发给相应的插件/主题。

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 install --save @docusaurus/preset-classic

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

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

预设路径可以是相对于配置文件的:

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

Creating presets​

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. 举个例子，你可以定义一个包含下列主题及插件的预设：

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 配置中，你可以转而设置使用上文所述的预设：

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

这与下列配置等同：

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

此方法非常适合需要整合某些插件及主题的情况。 你甚至可以把它们的选项关联在一起，比如把一个选项传递给多个插件。

Module shorthands​

Docusaurus 支持插件、主题和预设的名称简写。 当它看到一个插件/主题/预设名称时，它会试图按照以下顺序加载其中一个：

  • [name] (like content-docs)
  • @docusaurus/[moduleType]-[name] (like @docusaurus/plugin-content-docs)
  • docusaurus-[moduleType]-[name] (like docusaurus-plugin-content-docs)

where moduleType is one of 'preset', 'theme', 'plugin', depending on which field the module name is declared in. 第一个找到的模块会被加载。

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

If there is no name (like @jquery), [scope]/docusaurus-[moduleType] (i.e. @jquery/docusaurus-plugin) is loaded. 否则，会尝试下列名称：

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

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.

声明可能被解析成
awesomedocusaurus-plugin-awesome
sitemap@docusaurus/plugin-sitemap
@my-company@my-company/docusaurus-plugin (the only possible resolution!)
@my-company/awesome@my-company/docusaurus-plugin-awesome
@my-company/awesome/web@my-company/docusaurus-plugin-awesome/web