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

预设

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

使用预设

预设通常为 npm 软件包,所以您可以像其他 npm 包一样使用 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-presets')],
};

预设 -> 主题及插件

Presets are a shorthand function to add plugins and themes to your Docusaurus config. 举个例子,您可以指定包含下列主题及插件的预设:

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

The classic preset that is usually shipped by default to new Docusaurus website. 这是一系列插件及主题。

主题插件
@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: {},
},
},
],
],
};