配置扩展

您编写或使用的扩展可能需要额外的设置来配置其行为。虽然扩展可以利用播本或Antora正在构建的内容源中已有的信息，但直接配置扩展可能是必要的。扩展可以接受任意数量的属性，这些属性可以是嵌套的，并在播本文件中的条目中指定。这些属性可以通过传递给扩展的注册函数的名为config的上下文变量来访问。

基本配置

假设我们想发布一个名为humans.txt的文件，以表彰使文档站点成为可能的人员。我们将命名我们的扩展为humans-txt-extension.js。当然，扩展不知道要表彰谁，所以我们需要传递一些配置信息。

让我们首先在播本中注册我们的新扩展，并传递使用names键的人员列表。该键的值将是一个名称数组。

antora:
  extensions:
  - require: ./humans-txt-extension.js
    names:
    - Doc Writer
    - Dr. Austen
    - Emily Story

为了为额外的键腾出空间，我们将扩展的条目从单个（字符串）值转换为映射。要求请求值滑入require键。这样就有了定义其他键的空间，本例中是names。

现在让我们编写一个接受此配置并用它创建humans.txt文件的扩展：

示例 1. humans-txt-extension.js

module.exports.register = function ({ config }) {
  this.on('beforePublish', ({ siteCatalog }) => {
    const teamInfo = '/* TEAM */\n' + config.names.map((name) => `Name: ${name}`).join('\n')
    const contents = Buffer.from(teamInfo + '\n')
    siteCatalog.addFile({ contents, out: { path: 'humans.txt' } })
  })
}

扩展的config对象可以像任何其他上下文变量一样使用对象解构访问。由于JavaScript中的变量作用域，我们仍然可以在beforePublish事件的监听器中访问该变量。我们使用它提供的信息来填充humans.txt文件的内容，并将其添加到站点目录中。然后Antora将在发布站点中包含humans.txt文件。

配置键转换

在YAML中，键名使用蛇形命名约定。在JavaScript中，属性名使用驼峰命名约定。为了帮助解决播本文件中蛇形命名和JavaScript之间的驼峰命名不匹配问题，Antora会自动将蛇形命名的键名转换为配置对象上的驼峰属性。例如，Antora将cache_dir转换为cacheDir。大多数情况下，这不是问题。但是，如果您的扩展将配置或数据传递给另一个应用程序，这种转换可能会有问题。

配置数据

为了绕过这种配置，您可以将键隐藏在data键内部。data键内部的任何键（在任何深度）都会被传递而不会被修改。

假设我们想为humans.txt文件指定结构化内容。我们不需要Antora转换此结构化内容，因此我们可以将其存储在名为data的键内部。

antora:
  extensions:
  - require: ./humans-txt-extension.js
    data:
      TEAM:
      - Lead Writer: Doc Writer
        Contact: doc [at] example.org
        Location: Denver, CO
      - Information Architect: Dr. Austen
        Location: Winchester, Hampshire, England
      - Narrator: Emily Story
        Location: Antwerp, Belgium

现在，扩展可以迭代config.data中的键，并布局humans.txt文件的内容。

const contents = Buffer.from(
  Object.entries(config.data).reduce((accum, [category, entries]) => {
    if (accum.length) accum.push('')
    accum.push(`/* ${category} */`)
    entries.forEach((entry) => {
      accum.push('')
      for (const [key, val] of Object.entries(entry)) accum.push(`${key}: ${val}`)
    })
    return accum
  }, []).join('\n')
)