插件方法参考

注意

本节内容正在建设中。锚链接甚至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。

或者，如果预设包含该插件，则预设将负责将正确的选项传递给插件。由各个插件自行定义其接受的选项。

示例

这是一个对假设性插件实现的思维模型。

// 返回对象的 JavaScript 函数。
// `context` 由 Docusaurus 提供。示例：siteConfig 可以从 context 访问。
// `opts` 是用户定义的选项。
export default async function myPlugin(context, opts) {
  return {
    // 用作命名空间的强制字段，用于缓存每个插件的中间数据目录。
    // 如果你正在编写你自己的本地插件，你希望它是唯一的，以免与导入的插件发生潜在冲突。
    // 一个好方法是在其中添加你自己的项目名称。
    name: 'docusaurus-my-project-cool-plugin',

    async loadContent() {
      // loadContent 钩子在加载 siteConfig 和 env 之后执行。
      // 你可以返回一个 JavaScript 对象，该对象将传递给 contentLoaded 钩子。
    },

    async contentLoaded({content, actions}) {
      // contentLoaded 钩子在 loadContent 钩子完成后执行。
      // `actions` 是 Docusaurus 提供的一组功能性 API（例如 addRoute）
    },

    async postBuild(props) {
      // docusaurus <build> 完成后。
    },

    // TODO
    async postStart(props) {
      // docusaurus <start> 完成
    },

    // 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) {
      // 修改内部 webpack 配置。如果返回值是对象，则将使用 webpack-merge 合并到最终配置中；
      // 如果返回值是函数，它将接收 config 作为第一个参数，isServer 标志作为第二个参数。
    },

    getPathsToWatch() {
      // 要监视的路径。
    },

    getThemePath() {
      // 返回可以找到主题组件的目录的路径。
    },

    getClientModules() {
      // 返回要在客户端包中导入的模块的路径数组。这些模块在 React 甚至渲染初始 UI 之前全局导入。
    },

    extendCli(cli) {
      // 注册额外的命令以增强 Docusaurus 的 CLI
    },

    injectHtmlTags({content}) {
      // 注入 head 和/或 body HTML 标签。
    },

    async getTranslationFiles({content}) {
      // 返回翻译文件
    },

    translateContent({content, translationFiles}) {
      // 在此处翻译插件内容
    },

    translateThemeConfig({themeConfig, translationFiles}) {
      // 在此处翻译站点主题配置
    },

    async getDefaultCodeTranslationMessages() {
      // 在此处返回默认主题翻译
    },
  };
}

export function validateOptions({options, validate}) {
  const validatedOptions = validate(myValidationSchema, options);
  return validatedOptions;
}

export function validateThemeConfig({themeConfig, validate}) {
  const validatedThemeConfig = validate(myValidationSchema, options);
  return validatedThemeConfig;
}