跳到主要内容

扩展基础设施

道格龙（Docusaurus）拥有一些可被外部插件扩展的基础设施，例如热重载、CLI 和 swizzling。

getPathsToWatch()​

指定插件和主题需要监听的路径。开发服务器会监听这些路径，当内容发生变化时会重新加载插件生命周期。注意，插件和主题模块最初会接收来自 Node 的 context 和 options，你可以用它们获取站点的目录信息。

此方法适用于服务端消费的文件，因为主题文件会被 Webpack dev server 自动监听。

示例：

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

注册额外命令以增强道格龙 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 loader 会根据目标浏览器版本处理语法。

你还应使用 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 的情况下 swizzle。默认所有组件都被视为不稳定。如果返回空数组，则所有组件都不稳定；如果返回 undefined，则所有组件都被视为稳定。

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