扩展基础设施

¥Extending infrastructure

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

¥Docusaurus has some infrastructure like hot reloading, CLI, and swizzling, that can be extended by external plugins.

getPathsToWatch()

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

¥Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with context and options from Node, which you may use to find the necessary directory information about the site.

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

¥Use this for files that are consumed server-side, because theme files are automatically watched by Webpack dev server.

示例：

¥Example:

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 对象。

¥Register an extra command to enhance the CLI of Docusaurus. cli is a commander object.

警告

命令器版本很重要！我们使用 Commander v5，并确保你参考可用 API 的正确版本文档。

¥The commander version matters! We use commander v5, and make sure you are referring to the right version documentation for available APIs.

示例：

¥Example:

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，并使用其返回的路径来查找你的主题组件。相对路径根据包含入口点的文件夹进行解析。

¥Returns the path to the directory where the theme components can be found. When your users call swizzle, getThemePath is called and its returned path is used to find your theme components. Relative paths are resolved against the folder containing the entry point.

例如，你的 getThemePath 可以是：

¥For example, your getThemePath can be:

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 输出。

¥Similar to getThemePath(), it should return the path to the directory where the source code of TypeScript theme components can be found. This path is purely for swizzling TypeScript theme components, and theme components under this path will not be resolved by Webpack. Therefore, it is not a replacement for getThemePath(). Typically, you can make the path returned by getTypeScriptThemePath() be your source directory, and make the path returned by getThemePath() be the compiled JavaScript output.

提示

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

¥For TypeScript theme authors: you are strongly advised to make your compiled output as human-readable as possible. Only strip type annotations and don't transpile any syntaxes, because they will be handled by Webpack's Babel loader based on the targeted browser versions.

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

¥You should also format these files with Prettier. Remember—JS files can and will be directly consumed by your users.

示例：

¥Example:

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()

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

¥This is a static method, not attached to any plugin instance.

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

¥Returns a list of stable components that are considered safe for swizzling. These components will be swizzlable without --danger. All components are considered unstable by default. If an empty array is returned, all components are considered unstable. If undefined is returned, all components are considered stable.

my-theme/src/index.js

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