预设

预设是插件和主题的集合。

使用预设

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

• npm
• Yarn

npm install --save docusaurus-preset-name

yarn add docusaurus-preset-name

然后，在站点的 docusaurus.config.js 配置文件中的 presets 参数中进行配置：

module.exports = {
  // ...
  presets: ['@docusaurus/preset-xxxx'],

如需从本地目录加载预设，请指定如何解析它们：

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

预设即主题和插件的组合

预设是添加插件和主题到 docusaurus 配置文件中的一种快捷方式。 例如，你可以定义一个包含以下主题和插件的预设，

module.exports = function preset(context, opts = {}) {
  return {
    themes: [
      require.resolve('@docusaurus/themes-cool'),
      require.resolve('@docusaurus/themes-bootstrap'),
    ],
    plugins: [require.resolve('@docusaurus/plugin-blog')],
  };
};

然后在你的 Docusaurus 配置文件中使用此预设：

module.exports = {
  // ...
  presets: ['@docusaurus/preset-my-own'],

等同于以下方式：

module.exports = {
  themes: ['@docusaurus/themes-cool', '@docusaurus/themes-bootstrap'],
  plugins: ['@docusaurus/plugin-blog'],
};

当打算将某些插件和主题一起使用时，这种方式特别有用。

官方提供的预设

@docusaurus/preset-classic

通常默认情况下新建的 docusaurus 站点会自动添加 @docusaurus/preset-classic 预设。 此预设包含了一组插件和主题。

要单独为某个插件设置参数的话，只需为该插件设置所需的参数即可，例如，要为 @docusaurus/theme-classic 设置 customCss 参数的话，只需在预设中像下面这样设置即可：

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // debug 在开发环境（dev）中默认为 true，在生产环境（prod）中默认为 false 
        debug: undefined,
        // 以下参数将被直接传递给 @docusaurus/theme-classic。
        theme: {
          customCss: [require.resolve('./src/css/custom.css')],
        },
        // 以下参数将被直接传递给 @docusaurus/plugin-content-docs （设置为 false 则表示禁用此插件）
        docs: {},
        // 以下参数将被直接传递给 @docusaurus/plugin-content-blog （设置为 false 则表示禁用此插件）
        blog: {},
        // 以下参数将被直接传递给 @docusaurus/plugin-content-pages （设置为 false 则表示禁用此插件）
        pages: {},
        // 以下参数将被直接传递给 @docusaurus/plugin-content-sitemap （设置为 false 则表示禁用此插件）
        sitemap: {},
      },
    ],
  ],
};

除了这些插件和主题外，@docusaurus/theme-classic 将 remark-admonitions 作为 remark 插件添加到 @docusaurus/plugin-content-blog 和 @docusaurus/plugin-content-docs 中了。

admonitions 键将作为 参数（options） 传递给 remark-admonitions。若传递 false 将阻止将插件添加到 MDX。

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // 以下是传递给 remark-admonitions 的参数
          admonitions: {},
        },
      },
    ],
  ],
};

@docusaurus/preset-bootstrap

The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.

To specify plugin options individually, you can provide the necessary fields to certain plugins, i.e. docs for @docusaurus/theme-bootstrap, pass them in the preset field, like this:

module.exports = {
  presets: [
    [
      '@docusaurus/preset-bootstrap',
      {
        // Debug defaults to true in dev, false in prod
        debug: undefined,
        // Will be passed to @docusaurus/plugin-content-docs (false to disable)
        docs: {},
        // Will be passed to @docusaurus/plugin-content-blog (false to disable)
        blog: {},
      },
    ],
  ],
};

caution

此预设正在开发中