注册扩展

在Antora中注册扩展之前，扩展是不活动的。注册扩展有两种方式。您可以使用--extension CLI选项指定它，或者可以将其列为playbook文件中antora类别键下extensions键的条目。

一旦注册，Antora会按照在playbook文件中列出的顺序或传递给CLI的顺序调用扩展的注册函数。在playbook文件中的扩展在传递给CLI的扩展之前注册，尽管这个顺序可以通过根据请求启用已注册的扩展来改变。

CLI选项

一种快速注册（和启用）扩展而不修改playbook文件的方式是使用antora CLI提供的--extension选项。--extension CLI选项在运行时向Antora playbook的extensions键添加条目。

以下是如何使用此CLI选项注册我们的扩展的示例。

--extension ./my-extension.js

如果您有多个扩展需要注册，可以多次指定此选项。

使用CLI选项需要您每次运行Antora时键入较长的命令。因此，如果您总是要使用它，最好将其指定在playbook文件中。稍后您将了解，即使将其添加到playbook文件中，仍然可以使用CLI来控制何时激活它。

可以使用extensions键在playbook文件中注册Antora扩展。 extensions键在antora类别键下指定。 extensions键的值必须是数组。数组中的每个条目都可以是字符串或映射（键/值对）。

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

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

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

示例1. 带有扩展的antora-playbook.yml

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

我们使用./前缀来指示其位置相对于playbook文件。请参阅@antora/user-require-helper用法以了解Antora如何在playbook文件中解析require请求。

当您运行Antora时，您现在应该在终端中看到这样一行：

Antora正在构建示例文档。

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

示例2. 使用require键指定扩展的antora-playbook.yml

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

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

我们的下一步是为我们的扩展添加事件监听器。