跳转至主内容
Version: 2.0.0-beta.15

Using Plugins

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.

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.

我们有一份官方插件列表,而社群也开发了一些非官方插件。 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.

安装插件

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

npm install --save docusaurus-plugin-name

然后,您需要将其添加到站点中 docusaurus.config.jsplugins 选项:

docusaurus.config.js
module.exports = {
// ...
plugins: ['@docusaurus/plugin-content-pages'],
};

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

docusaurus.config.js
const path = require('path');

module.exports = {
// ...
plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],
};

配置插件

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

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
module.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-xxx',
{
/* options */
},
],
],
};

示例:

docusaurus.config.js
module.exports = {
plugins: [
// 基础用法
'@docusaurus/plugin-debug',

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

多实例插件及插件 ID

所有的 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
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'docs-1',
// other options
},
],
[
'@docusaurus/plugin-content-docs',
{
id: 'docs-2',
// other options
},
],
],
};
note

仅有一个插件实例可作为 "默认插件实例"。您可缺省 id 属性或使用 id: 'default' 来将其设为默认。

使用主题

Themes are loaded in the exact same way as plugins—the line between them is blurry. 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.

tip

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
module.exports = {
// ...
themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

使用预设

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

npm install --save @docusaurus/preset-classic

然后,将其添加到站点中 docusaurus.config.jspresets 选项:

docusaurus.config.js
module.exports = {
// ...
presets: ['@docusaurus/preset-classic'],
};

要加载您本地目录的预设,请指定如何进行解析:

docusaurus.config.js
const path = require('path');

module.exports = {
// ...
presets: [path.resolve(__dirname, '/path/to/docusaurus-local-preset')],
};

Presets are a shorthand function to add plugins and themes to your Docusaurus config. For example, you can specify a preset that includes the following themes and plugins:

/path/to/docusaurus-local-preset
module.exports = 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
module.exports = {
presets: [
[
path.resolve(__dirname, '/path/to/docusaurus-local-preset'),
{
theme: {hello: 'world'},
docs1: {path: '/docs'},
docs2: {path: '/community'},
docs3: {path: '/api'},
},
],
],
};

这与下列配置等同:

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

此方法非常适合需要整合部分插件及主题的情况。 You can even link their options together, e.g. pass one option to multiple plugins.

@docusaurus/preset-classic

The classic preset is shipped by default to new Docusaurus website created with create-docusaurus. 这是一系列插件及主题。

主题插件
@docusaurus/theme-classic@docusaurus/plugin-content-docs
@docusaurus/theme-search-algolia@docusaurus/plugin-content-blog
@docusaurus/plugin-content-pages
@docusaurus/plugin-debug
@docusaurus/plugin-google-analytics
@docusaurus/plugin-google-gtag
@docusaurus/plugin-sitemap

要为插件单独设置选项,您需要为其提供单独的字段,如为 @docusaurus/theme-classic 提供 customCss 选项,并按如下所示的方式传递至预设字段中:

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// 调试在开发环境中默认为 true,而在生产环境中为 false
debug: undefined,
// 将传递至 @docusaurus/theme-classic。
theme: {
customCss: [require.resolve('./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-content-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-analytics (only enabled when explicitly specified)
googleAnalytics: {},
},
],
],
};

除了这些插件及主题之外,@docusaurus/theme-classic 还为 @docusaurus/plugin-content-blog@docusaurus/plugin-content-docs 添加了 remark-admonitions Remark 插件。

admonitions 键值将作为 options 选项传递至 remark-admonitions。 传递 false 将防止插件添加到 MDX 中。

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// remark-admonitions 选项
admonitions: {},
},
},
],
],
};

Module shorthands

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]
  • @docusaurus/[moduleType]-[name]
  • docusaurus-[moduleType]-[name],

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

If the name is not specified, {scope}/docusaurus-{type} is loaded. Otherwise, the following are attempted:

  • [scope]/[name]
  • [scope]/docusaurus-[moduleType]-[name]

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.

DeclarationMay be resolved as
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