跳到主要内容
版本:3.0.0-rc.1

插件方法总览

注意

此章节尚未完成。 锚点链接,甚至是 URL,都不保证稳定。

插件 API 由主题和插件共享——主题的加载与插件是一样的。

Plugin module

每个插件都被作为模块导入。 模块应该有以下成员:

  • A default export: the constructor function for the plugin.
  • Named exports: the static methods called before plugins are initialized.

Plugin constructor

The plugin module's default export is a constructor function with the signature (context: LoadContext, options: PluginOptions) => Plugin | Promise<Plugin>.

context

context is plugin-agnostic, and the same object will be passed into all plugins used for a Docusaurus website. The context object contains the following fields:

type LoadContext = {
siteDir: string;
generatedFilesDir: string;
siteConfig: DocusaurusConfig;
outDir: string;
baseUrl: string;
};

options

options are the second optional parameter when the plugins are used. options are plugin-specific and are specified by users when they use them in docusaurus.config.js. If there's a validateOptions function exported, the options will be validated and normalized beforehand.

另外,如果插件是被预设包含的,那么预设就会负责为插件提供正确配置选项。 插件本身会决定需要哪些设置。

Example

这是一个假想的插件实现。

// 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.org/configuration/dev-server/#devserverbefore
},

// TODO
beforeDevServer(app, server) {
// https://webpack.js.org/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;
}