插件方法参考

注意

本节正在编写中。锚点链接或 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 提供。例如：可以从 context 访问 siteConfig。
// `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 合并到最终配置中；
      // 如果返回值是一个函数，它将接收配置作为第一个参数，isServer 标志作为第二个参数。
    },

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

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

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

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

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

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

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

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

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