注册扩展

在 Antora 注册之前，扩展处于非激活状态。注册扩展有两种方法。您可以将其列为 playbook 文件中 antora 类别键下的 extensions 键条目，或使用 --extension CLI 选项指定。--extension CLI 选项会在运行时向 extensions 键添加条目。

注册后，Antora 将按照扩展在 playbook 文件中列出或传递到 CLI 的顺序调用扩展的注册函数。 Playbook 文件中的扩展在传递到 CLI 的扩展之前注册，尽管可以通过根据请求启用已注册的扩展来更改此顺序。

扩展键

extensions 键在 playbook 文件中的 antora 类别键下指定。 extensions 键的值必须是一个数组。数组中的每个条目都是字符串或映射（键/值对）。

当该值为字符串时，该值被假定为解析为扩展脚本的 require 请求（即路径或模块名称）。当值为 map 时，必须使用 require 键指定 require 请求。使用 map 为额外的配置键留出空间，包括预定义的（如 enabled）和自定义的。

如果您要将扩展发布到包存储库，则 require 请求将是该包的名称（即其模块名称）。在这种情况下，请确保将该包配置为 playbook 项目的依赖项，以便 Node.js 获取它。Antora 不会为您下载 npm 软件包。

Without configuration

让我们在 playbook 文件中注册我们的扩展，以便我们可以看到它的运行情况。在最简单的形式中，扩展条目是扩展脚本的 require 请求（即路径）。

Example 1. antora-playbook.yml with extension

antora:
  extensions:
  - ./my-extension.js

我们为路径添加前缀 ./ 以指示其位置相对于 playbook 文件。请参阅 @antora/user-require-helper 用法，了解 Antora 如何解析 playbook 文件中的 require 请求。

当您运行 Antora 时，您现在应该在终端中看到如下行：

Antora is building the Example Docs.

With configuration

如果您需要指定扩展的配置设置，则必须将条目类型从字符串更改为映射。进行此更改时，现在必须在 require 键上指定 require 请求。

Example 2. antora-playbook.yml with extension specified using require key

antora:
  extensions:
  - require: ./my-extension.js
    optional_behavior: true

通过使用 map，可以将其他键添加为 require 键的同级键，以便将配置传递给扩展。您可以在配置扩展页面上找到如何使用这些附加键来配置扩展的示例。

我们的下一步是将事件侦听器添加到我们的扩展中。