Skip to main content

预设

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

使用预设

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

npm install --save @docusaurus/preset-classic

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

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

预设即主题和插件的组合

预设(preset)在某种程度上来讲是一种快捷函数,用于将插件和主题添加到 docusaurus 的配置文件中。 例如,你可以指定一个包含以下主题和插件的预设,

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

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

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

等同于以下方式:

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

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

官方提供的预设

@docusaurus/preset-classic

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

主题插件
@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',
{
// 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: {},
// 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-classicremark-admonitions 作为 remark 插件添加到 @docusaurus/plugin-content-blog@docusaurus/plugin-content-docs 中了。

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

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