扩展基础设施

Docusaurus 拥有热重载、CLI 和代码混淆等一些基础设施，这些基础设施可以通过外部插件扩展。

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 主题组件源代码所在目录的路径。此路径纯粹用于混淆 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()

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

返回被认为可以安全混淆的稳定组件列表。这些组件无需 --danger 即可混淆。默认情况下，所有组件都被视为不稳定。如果返回空数组，则所有组件都被视为不稳定。如果返回 undefined，则所有组件都被视为稳定。

my-theme/src/index.js

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