扩展基础设施

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() {
      // Where compiled JavaScript output lives
      return '../lib/theme';
    },
    getTypeScriptThemePath() {
      // Where TypeScript source code lives
      return '../src/theme';
    },
  };
}

getSwizzleComponentList()

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

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

my-theme/src/index.js

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