插件方法引用
警告
本节内容正在编写中。锚链接甚至 URL 均不保证稳定。
主题和插件共享插件 API——主题的加载方式与插件相同。
插件模块
每个插件都作为一个模块导入。该模块应包含以下成员:
- 一个默认导出:即插件的构造函数。
- 命名导出:在插件初始化之前调用的静态方法。
插件构造函数
插件模块的默认导出是一个构造函数,其签名是 (context: LoadContext, options: PluginOptions) => Plugin | Promise<Plugin>
。
context
context
与插件无关,并且相同对象将传递给 Docusaurus 网站使用的所有插件。context
对象包含以下字段:
type LoadContext = {
siteDir: string;
generatedFilesDir: string;
siteConfig: DocusaurusConfig;
outDir: string;
baseUrl: string;
};
options
options
是使用插件时的第二个可选参数。options
是插件特有的,由用户在 docusaurus.config.js
中使用插件时指定。如果存在导出的 validateOptions
函数,则 options
将在之前进行验证和规范化。
或者,如果一个预设包含该插件,则该预设将负责向插件传递正确的选项。每个插件自行定义它接受哪些选项。
示例
这是一个推测性插件实现的思维模型。
// A JavaScript function that returns an object.
// `context` is provided by Docusaurus. Example: siteConfig can be accessed from context.
// `opts` is the user-defined options.
export default async function myPlugin(context, opts) {
return {
// A compulsory field used as the namespace for directories to cache
// the intermediate data for each plugin.
// If you're writing your own local plugin, you will want it to
// be unique in order not to potentially conflict with imported plugins.
// A good way will be to add your own project name within.
name: 'docusaurus-my-project-cool-plugin',
async loadContent() {
// The loadContent hook is executed after siteConfig and env has been loaded.
// You can return a JavaScript object that will be passed to contentLoaded hook.
},
async contentLoaded({content, actions}) {
// The contentLoaded hook is done after loadContent hook is done.
// `actions` are set of functional API provided by Docusaurus (e.g. addRoute)
},
async postBuild(props) {
// After docusaurus <build> finish.
},
// TODO
async postStart(props) {
// docusaurus <start> finish
},
// TODO
afterDevServer(app, server) {
// https://webpack.js.cn/configuration/dev-server/#devserverbefore
},
// TODO
beforeDevServer(app, server) {
// https://webpack.js.cn/configuration/dev-server/#devserverafter
},
configureWebpack(config, isServer, utils, content) {
// Modify internal webpack config. If returned value is an Object, it
// will be merged into the final config using webpack-merge;
// If the returned value is a function, it will receive the config as the 1st argument and an isServer flag as the 2nd argument.
},
getPathsToWatch() {
// Paths to watch.
},
getThemePath() {
// Returns the path to the directory where the theme components can
// be found.
},
getClientModules() {
// Return an array of paths to the modules that are to be imported
// in the client bundle. These modules are imported globally before
// React even renders the initial UI.
},
extendCli(cli) {
// Register an extra command to enhance the CLI of Docusaurus
},
injectHtmlTags({content}) {
// Inject head and/or body HTML tags.
},
async getTranslationFiles({content}) {
// Return translation files
},
translateContent({content, translationFiles}) {
// translate the plugin content here
},
translateThemeConfig({themeConfig, translationFiles}) {
// translate the site themeConfig here
},
async getDefaultCodeTranslationMessages() {
// return default theme translations here
},
};
}
export function validateOptions({options, validate}) {
const validatedOptions = validate(myValidationSchema, options);
return validatedOptions;
}
export function validateThemeConfig({themeConfig, validate}) {
const validatedThemeConfig = validate(myValidationSchema, options);
return validatedThemeConfig;
}