跳转至主内容
Version: 2.0.0-alpha.75

预设

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

使用预设#

预设通常为 npm 软件包,所以您可以像其他 npm 包一样使用 npm 安装。

npm install --save docusaurus-preset-name

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

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

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

docusaurus.config.js
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 配置中,您可转而设置使用上文所述的预设:

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

这与下列配置等同:

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

此方法非常适合需要整合部分插件及主题的情况。

官方预设#

@docusaurus/preset-classic#

新 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')],        },        // 将传递至 @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 还为 @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: {},        },      },    ],  ],};

@docusaurus/preset-bootstrap#

新 Docusaurus 站点默认自带的经典预设。 这是一系列插件及主题。

主题插件
@docusaurus/theme-bootstrap@docusaurus/plugin-content-docs
@docusaurus/plugin-content-blog
@docusaurus/plugin-content-pages
@docusaurus/plugin-debug

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

docusaurus.config.js
module.exports = {  presets: [    [      '@docusaurus/preset-bootstrap',      {        // 调试在开发环境中默认为 true,而在生产环境中为 false        debug: undefined,        // 将传递至 @docusaurus/plugin-content-docs(设置为 false 以禁用)        docs: {},        // 将传递至 @docusaurus/plugin-content-blog(设置为 false 以禁用)        blog: {},      },    ],  ],};
注意

此预设仍在开发中。