插件方法参考

注意

本章节仍在完善中。锚点链接或 URL 可能会变动，请勿依赖其稳定性。

插件 API 由主题和插件共享——主题的加载方式与插件一致。

插件模块

每个插件都以模块形式导入。该模块应包含以下成员：

• 默认导出：插件的构造函数。
• 具名导出：在插件初始化前调用的静态方法。

插件构造函数

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

context

context 与插件无关，所有插件都会接收到同一个 context 对象。context 包含以下字段：

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

options

options 是插件使用时的第二个可选参数。options 由用户在 docusaurus.config.js 中指定，具体内容由插件自行定义。如果模块导出了 validateOptions 方法，则 options 会在传递前被校验和规范化。

另外，如果插件由预设引入，则预设会负责传递正确的 options。每个插件可自定义其支持的 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 加载后执行。
      // 你可以返回一个对象，该对象会传递给 contentLoaded 钩子。
    },

    async contentLoaded({content, actions}) {
      // contentLoaded 钩子在 loadContent 完成后执行。
      // `actions` 是道格龙提供的一组功能 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) {
      // 注册额外命令，扩展道格龙 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;
}