扩大基础设施

Docusaurus 有一些基础设施，如热重新加载、CLI 和 swizzling，可以通过外部插件进行扩展。

getPathsToWatch()

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

将此用于服务器端使用的文件，因为主题文件由 Webpack 开发服务器自动监视。

例子:

docusaurus-plugin/src/index.js

const path = require("path");
module.exports = 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

module.exports = 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

const path = require("path");

module.exports = 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

const path = require("path");

module.exports = 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

const swizzleAllowedComponents = [
  "CodeBlock",
  "DocSidebar",
  "Footer",
  "NotFound",
  "SearchBar",
  "hooks/useTheme",
  "prism-include-languages",
];

myTheme.getSwizzleComponentList = () => swizzleAllowedComponents;