跳到主要内容
版本:Canary 🚧

生命周期 API

在构建过程中,插件会被并行加载,各自获取自己的内容并将它们变成路由。 插件还可以配置 webpack 或后处理构建生成的文件。

async loadContent()

插件应该使用这个生命周期从数据源(文件系统、远程 API、无头 CMS 等)获取数据,或进行某些服务端的处理。 返回值是它需要的内容。

比如,下面的插件会返回 1 到 10 之间的一个随机整数作为内容。

docusaurus-plugin/src/index.js
export default function (context, options) {
return {
name: 'docusaurus-plugin',
async loadContent() {
return 1 + Math.floor(Math.random() * 10);
},
};
}

async contentLoaded({content, actions})

loadContent 所加载的数据会在 contentLoaded 中被读取。 数据可以被渲染成路由,注册为全局数据,等等。

content

contentLoaded 会在 loadContent 完成_之后_被调用。 loadContent() 的返回值会被作为 content 传递给 contentLoaded

actions

actions 包含三个函数:

addRoute(config: RouteConfig): void

为网站新增一条路由。

export type RouteConfig = {
/**
* With leading slash. Trailing slash will be normalized by config.
*/
path: string;
/**
* Component used to render this route, a path that the bundler can `require`.
*/
component: string;
/**
* Props. Each entry should be `[propName]: pathToPropModule` (created with
* `createData`)
*/
modules?: RouteModules;
/**
* The route context will wrap the `component`. Use `useRouteContext` to
* retrieve what's declared here. Note that all custom route context declared
* here will be namespaced under {@link RouteContext.data}.
*/
context?: RouteModules;
/**
* Nested routes config, useful for "layout routes" having subroutes.
*/
routes?: RouteConfig[];
/**
* React router config option: `exact` routes would not match subroutes.
*/
exact?: boolean;
/**
* React router config option: `strict` routes are sensitive to the presence
* of a trailing slash.
*/
strict?: boolean;
/**
* Used to sort routes.
* Higher-priority routes will be matched first.
*/
priority?: number;
/**
* Optional route metadata
*/
metadata?: RouteMetadata;
/**
* Extra props; will be available on the client side.
*/
[propName: string]: unknown;
};

/**
* Plugin authors can assign extra metadata to the created routes
* It is only available on the Node.js side, and not sent to the browser
* Optional: plugin authors are encouraged but not required to provide it
*
* Some plugins might use this data to provide additional features.
* This is the case of the sitemap plugin to provide support for "lastmod".
* See also: https://github.com/facebook/docusaurus/pull/9954
*/
export type RouteMetadata = {
/**
* The source code file path that led to the creation of the current route
* In official content plugins, this is usually a Markdown or React file
* This path is expected to be relative to the site directory
*/
sourceFilePath?: string;
/**
* The last updated date of this route
* This is generally read from the Git history of the sourceFilePath
* but can also be provided through other means (usually front matter)
*
* This has notably been introduced for adding "lastmod" support to the
* sitemap plugin, see https://github.com/facebook/docusaurus/pull/9954
*/
lastUpdatedAt?: number;
};

type RouteModules = {
[module: string]: Module | RouteModules | RouteModules[];
};

type Module =
| {
path: string;
__import?: boolean;
query?: ParsedUrlQueryInput;
}
| string;

createData(name: string, data: any): Promise<string>

一个声明式的回调,用来创建静态数据(一般为 JSON 或字符串),之后可以作为 props 提供给你的路由。 接收要存储的文件名和数据,并返回数据文件的真实路径。

比如,下面的插件会创建一个 /friends 页面,显示 你的朋友是: Yangshun, Sebastien

website/src/components/Friends.js
import React from 'react';

export default function FriendsComponent({friends}) {
return <div>你的朋友是:{friends.join(',')}</div>;
}
docusaurus-friends-plugin/src/index.js
export default function friendsPlugin(context, options) {
return {
name: 'docusaurus-friends-plugin',
async contentLoaded({content, actions}) {
const {createData, addRoute} = actions;
// 创建 friends.json
const friends = ['Yangshun', 'Sebastien'];
const friendsJsonPath = await createData(
'friends.json',
JSON.stringify(friends),
);

// 添加 '/friends' 路由,并确保它收到了 friends prop
addRoute({
path: '/friends',
component: '@site/src/components/Friends.js',
modules: {
// 从 prop 名称 -> JSON 文件路径
friends: friendsJsonPath,
},
exact: true,
});
},
};
}

setGlobalData(data: any): void

这个函数允许创建全局插件数据,在任何页面都可以被读取,包括其他插件创建的页面以及你的主题布局。

This data becomes accessible to your client-side/theme code through the useGlobalData and usePluginData hooks.

警告

全局数据是……全局的:它的体积会影响你的网站的每一页的加载时间,所以把它弄小一点。 如果可能,请选择用 createDate 创建页面专有的数据。

比如,下面的插件会创建一个 /friends 页面,显示 你的朋友是: Yangshun, Sebastien

website/src/components/Friends.js
import React from 'react';
import {usePluginData} from '@docusaurus/useGlobalData';

export default function FriendsComponent() {
const {friends} = usePluginData('docusaurus-friends-plugin');
return <div>Your friends are {friends.join(',')}</div>;
}
docusaurus-friends-plugin/src/index.js
export default function friendsPlugin(context, options) {
return {
name: 'docusaurus-friends-plugin',
async contentLoaded({content, actions}) {
const {setGlobalData, addRoute} = actions;
// 生成全局朋友数据
setGlobalData({friends: ['Yangshun', 'Sebastien']});

// 添加 '/friends' 路径
addRoute({
path: '/friends',
component: '@site/src/components/Friends.js',
exact: true,
});
},
};
}

configureWebpack(config, isServer, utils, content)

修改内部的 webpack 配置。 如果返回值是一个 JavaScript 对象,它会通过 webpack-merge 被合并入最终配置。 如果返回值是函数, 它会被调用,第一个参数为 config,第二个参数为 isServer 标识。

警告

configureWebpack 的 API 未来会被修改为接受一个对象(configureWebpack({config, isServer, utils, content}))

config

configureWebpack 在调用时会接受 config,由 Docusaurus 根据当前为客户端还是服务端构建生成。 你可以把它当作是会被和你的配置合并的基本配置。

isServer

configureWebpack 会在服务端构建和客户端构建时都被调用。 isServer 会在服务端构建时为 true,在客户端构建时为 false

utils

configureWebpack 也会接受一个包含了一些工具的对象:

  • getStyleLoaders(isServer: boolean, cssOptions: {[key: string]: any}): Loader[]
  • getJSLoader(isServer: boolean, cacheOptions?: {}): Loader | null

你可以用它们来条件性地返回你的 webpack 配置。

例如,下面的插件修改了 webpack 配置,让它能够转译 .foo 文件。

docusaurus-plugin/src/index.js
export default function (context, options) {
return {
name: 'custom-docusaurus-plugin',
configureWebpack(config, isServer, utils) {
const {getJSLoader} = utils;
return {
module: {
rules: [
{
test: /\.foo$/,
use: [getJSLoader(isServer), 'my-custom-webpack-loader'],
},
],
},
};
},
};
}

content

configureWebpack 还会接受插件所加载的内容。

合并策略

我们会用 webpack-merge 把插件返回的 Webpack 配置片段合并到全局配置中。

插件可以声明合并策略。 比如,如果你希望某条 Webpack 规则被放到前面而不是后面:

docusaurus-plugin/src/index.js
export default function (context, options) {
return {
name: 'custom-docusaurus-plugin',
configureWebpack(config, isServer, utils) {
return {
mergeStrategy: {'module.rules': 'prepend'},
module: {rules: [myRuleToPrepend]},
};
},
};
}

阅读 webpack-merge 策略的文档了解更多详情。

配置开发服务器

可以通过返回 devServer 字段来配置开发服务器。

docusaurus-plugin/src/index.js
export default function (context, options) {
return {
name: 'custom-docusaurus-plugin',
configureWebpack(config, isServer, utils) {
return {
devServer: {
open: '/docs', // Opens localhost:3000/docs instead of localhost:3000/
},
};
},
};
}

configurePostCss(options)

在生成客户端包裹时修改 postcss-loaderpostcssOptions

应返回修改过的 postcssOptions

默认情况下,postcssOptions 长得像这样:

const postcssOptions = {
ident: 'postcss',
plugins: [require('autoprefixer')],
};

示例:

docusaurus-plugin/src/index.js
export default function (context, options) {
return {
name: 'docusaurus-plugin',
configurePostCss(postcssOptions) {
// 添加新 PostCSS 插件。
postcssOptions.plugins.push(require('postcss-import'));
return postcssOptions;
},
};
}

postBuild(props)

在生产构建完成时被调用。

interface Props {
siteDir: string;
generatedFilesDir: string;
siteConfig: DocusaurusConfig;
outDir: string;
baseUrl: string;
headTags: string;
preBodyTags: string;
postBodyTags: string;
routesPaths: string[];
plugins: Plugin<any>[];
content: Content;
}

示例:

docusaurus-plugin/src/index.js
export default function (context, options) {
return {
name: 'docusaurus-plugin',
async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
// 在控制台打印所有渲染的路径。
routesPaths.map((route) => {
console.log(route);
});
},
};
}

injectHtmlTags({content})

在 Docusaurus 生成的 HTML 中注入 head 或 body HTML 标签。

injectHtmlTags 也会接受插件加载的内容。

function injectHtmlTags(): {
headTags?: HtmlTags;
preBodyTags?: HtmlTags;
postBodyTags?: HtmlTags;
};

type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];

type HtmlTagObject = {
/**
* HTML 标签的属性
* 比如 `{'disabled': true, 'value': 'demo', 'rel': 'preconnect'}`
*/
attributes?: {
[attributeName: string]: string | boolean;
};
/**
* 标签的名称,比如 `div`, `script`, `link`, `meta`
*/
tagName: string;
/**
* inner HTML
*/
innerHTML?: string;
};

示例:

docusaurus-plugin/src/index.js
export default function (context, options) {
return {
name: 'docusaurus-plugin',
loadContent: async () => {
return {remoteHeadTags: await fetchHeadTagsFromAPI()};
},
injectHtmlTags({content}) {
return {
headTags: [
{
tagName: 'link',
attributes: {
rel: 'preconnect',
href: 'https://www.github.com',
},
},
...content.remoteHeadTags,
],
preBodyTags: [
{
tagName: 'script',
attributes: {
charset: 'utf-8',
src: '/noflash.js',
},
},
],
postBodyTags: [`<div> This is post body </div>`],
};
},
};
}

Tags will be added as follows:

  • headTags will be inserted before the closing </head> tag after scripts added by config.
  • preBodyTags will be inserted after the opening <body> tag before any child elements.
  • postBodyTags will be inserted before the closing </body> tag after all child elements.

getClientModules()

Returns an array of paths to the client modules that are to be imported into the client bundle.

作为例子,如果你的主题会根据用户提供的 options 加载 customCsscustomJs 文件:

my-theme/src/index.js
export default function (context, options) {
const {customCss, customJs} = options || {};
return {
name: 'name-of-my-theme',
getClientModules() {
return [customCss, customJs];
},
};
}