插件方法参考

¥Plugin Method References

警告

本部分正在进行中。锚链接甚至 URL 都不能保证稳定。

¥This section is a work in progress. Anchor links or even URLs are not guaranteed to be stable.

插件 API 由主题和插件共享 - 主题的加载就像插件一样。

¥Plugin APIs are shared by themes and plugins—themes are loaded just like plugins.

插件模块

¥Plugin module

每个插件都作为模块导入。该模块预计将有以下成员：

¥Every plugin is imported as a module. The module is expected to have the following members:

• 默认导出：插件的构造函数。

  ¥A default export: the constructor function for the plugin.

• 命名导出：插件初始化之前调用的 静态方法。

  ¥Named exports: the static methods called before plugins are initialized.

插件构造函数

¥Plugin constructor

插件模块的默认导出是带有签名 (context: LoadContext, options: PluginOptions) => Plugin | Promise<Plugin> 的构造函数。

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

context

context 与插件无关，相同的对象将被传递到 Docusaurus 网站使用的所有插件中。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 是 使用插件时的第二个可选参数。options 是特定于插件的，由用户在 docusaurus.config.js 中使用时指定。如果导出了 validateOptions 函数，则 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.

或者，如果预设包含插件，则预设将负责将正确的选项传递到插件中。由各个插件来定义它需要哪些选项。

¥Alternatively, if a preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to the individual plugin to define what options it takes.

示例

¥Example

这是一个自以为是的插件实现的心理模型。

¥Here's a mental model for a presumptuous plugin implementation.

// 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;
}