扩展基础设施

Docusaurus 有一些基础设施，如热重载、CLI 和 swizzling，可以由外部插件扩展。

getPathsToWatch()

指定插件和主题要监视的路径。开发服务器会监视这些路径，以便在监视路径中的内容发生变化时重新加载插件生命周期。请注意，插件和主题模块最初是使用来自 Node 的 context 和 options 调用的，您可以使用这些信息找到关于站点的必要目录信息。

对于服务器端使用的文件使用此方法，因为主题文件会被 Webpack 开发服务器自动监视。

示例：

docusaurus-plugin/src/index.js

import path from 'path';

export default function (context, options) {
  return {
    name: 'docusaurus-plugin',
    getPathsToWatch() {
      const contentPath = path.resolve(context.siteDir, options.path);
      return [`${contentPath}/**/*.{ts,tsx}`];
    },
  };
}

extendCli(cli)

注册额外的命令以增强 Docusaurus 的 CLI。cli 是一个 commander 对象。

注意

commander 版本很重要！我们使用 commander v5，请确保您参考的是正确版本的文档以获取可用的 API。

示例：

docusaurus-plugin/src/index.js

export default function (context, options) {
  return {
    name: 'docusaurus-plugin',
    extendCli(cli) {
      cli
        .command('roll')
        .description('Roll a random number between 1 and 1000')
        .action(() => {
          console.log(Math.floor(Math.random() * 1000 + 1));
        });
    },
  };
}

getThemePath()

返回可以找到主题组件的目录路径。当用户调用 swizzle 时，将调用 getThemePath，并使用其返回的路径查找主题组件。相对路径将相对于包含入口点的文件夹进行解析。

例如，您的 getThemePath 可以是：

my-theme/src/index.js

export default function (context, options) {
  return {
    name: 'my-theme',
    getThemePath() {
      return './theme';
    },
  };
}

getTypeScriptThemePath()

类似于 getThemePath()，它应返回可以找到 TypeScript 主题组件源代码的目录路径。此路径纯粹用于 swizzling TypeScript 主题组件，并且此路径下的主题组件不会被 Webpack 解析。因此，它不是 getThemePath() 的替代品。通常，您可以使 getTypeScriptThemePath() 返回的路径成为您的源目录，并使 getThemePath() 返回的路径成为编译后的 JavaScript 输出。

提示

对于 TypeScript 主题作者：强烈建议使您的编译输出尽可能易于阅读。仅去除类型注释，不要转译任何语法，因为它们将由 Webpack 的 Babel 加载器根据目标浏览器版本处理。

您还应该使用 Prettier 格式化这些文件。请记住 - JS 文件可以并且将直接被您的用户使用。

示例：

my-theme/src/index.js

export default function (context, options) {
  return {
    name: 'my-theme',
    getThemePath() {
      // 编译后的 JavaScript 输出所在位置
      return '../lib/theme';
    },
    getTypeScriptThemePath() {
      // TypeScript 源代码所在位置
      return '../src/theme';
    },
  };
}

getSwizzleComponentList()

这是一个静态方法，不附加到任何插件实例。

返回被认为可安全 swizzling 的稳定组件列表。这些组件可以在没有 --danger 的情况下进行 swizzling。默认情况下，所有组件都被视为不稳定。如果返回空数组，则所有组件都被视为不稳定。如果返回 undefined，则所有组件都被视为稳定。

my-theme/src/index.js

export function getSwizzleComponentList() {
  return [
    'CodeBlock',
    'DocSidebar',
    'Footer',
    'NotFound',
    'SearchBar',
    'hooks/useTheme',
    'prism-include-languages',
  ];
}