扩展基础设施

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('掷一个 1 到 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',
  ];
}