使用插件

道格龙（Docusaurus）核心本身不提供任何功能。 所有功能都委托给各个插件：由文档插件提供的文档功能；由博客插件提供的博客功能；或由页面插件提供的单个页面。如果没有安装任何插件，网站将不包含任何路由。

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

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

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

安装插件

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

npm
Yarn
pnpm
Bun

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

道格龙（Docusaurus）也可以从你的本地目录加载插件，如下所示：

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

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

配置插件

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

此外，插件还可以通过在你的配置中将名称和选项对象包装在一个两元组中来指定选项。这种风格通常被称为“Babel 风格”。

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

示例：

docusaurus.config.js
export default {
  plugins: [
    // 基本用法
    '@docusaurus/plugin-debug',

    // 带选项对象（Babel 风格）
    [
      '@docusaurus/plugin-sitemap',
      {
        changefreq: 'weekly',
      },
    ],
  ],
};

多实例插件和插件 ID

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

docusaurus.config.js
export default {
  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
export default {
  // ...
  themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

使用预设

预设是插件和主题的捆绑包。例如，我们有 @docusaurus/preset-classic 预设，它允许你在一个集中的地方配置它们，而不是让你在配置文件中一个接一个地注册和配置 @docusaurus/plugin-content-docs、@docusaurus/plugin-content-blog 等。

`@docusaurus/preset-classic`

classic 预设是使用 create-docusaurus 创建的新道格龙（Docusaurus）网站默认附带的。它包含以下主题和插件：

classic 预设会将每个选项条目中继到相应的插件/主题。

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // Debug 在开发模式下默认为 true，在生产模式下为 false
        debug: undefined,
        // 将传递给 @docusaurus/theme-classic
        theme: {
          customCss: ['./src/css/custom.css'],
        },
        // 将传递给 @docusaurus/plugin-content-docs (false 表示禁用)
        docs: {},
        // 将传递给 @docusaurus/plugin-content-blog (false 表示禁用)
        blog: {},
        // 将传递给 @docusaurus/plugin-content-pages (false 表示禁用)
        pages: {},
        // 将传递给 @docusaurus/plugin-sitemap (false 表示禁用)
        sitemap: {},
        // 将传递给 @docusaurus/plugin-svgr (false 表示禁用)
        svgr: {},
        // 将传递给 @docusaurus/plugin-google-gtag (仅在明确指定时启用)
        gtag: {},
        // 将传递给 @docusaurus/plugin-google-tag-manager (仅在明确指定时启用)
        googleTagManager: {},
        // 已弃用: 将传递给 @docusaurus/plugin-google-analytics (仅在明确指定时启用)
        googleAnalytics: {},
      },
    ],
  ],
};

安装预设

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

npm
Yarn
pnpm
Bun

npm 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.js
export default {
  // ...
  presets: ['@docusaurus/preset-classic'],
};

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

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

创建预设

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

src/presets/docusaurus-preset-multi-docs.js
export default function preset(context, opts = {}) {
  return {
    themes: [['docusaurus-theme-awesome', opts.theme]],
    plugins: [
      // 同时使用三个文档插件！
      // 为每个插件分配唯一的 ID，而无需用户手动操作
      ['@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'}],
  ],
};

这在某些插件和主题旨在协同使用时特别有用。你甚至可以将它们的选项链接在一起，例如，将一个选项传递给多个插件。

模块简写

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

[name] (例如 content-docs)
@docusaurus/[moduleType]-[name] (例如 @docusaurus/plugin-content-docs)
docusaurus-[moduleType]-[name] (例如 docusaurus-plugin-content-docs)

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

如果名称是带作用域的（以 @ 开头），则名称首先会按第一个斜杠分割为作用域和包名：

@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）允许更大的命名自由度，因此解析不是确定的，但遵循上面定义的优先级。

声明	可能解析为
`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​

安装预设​

创建预设​

模块简写​