Upgrade Antora :: Antora Docs

从 Antora 2.3 升级到 Antora 3.1 检查清单

Antora 2 已终止支持。如果您当前正在使用 Antora 2，您可能需要在升级到 Antora 3.1 之前对文档系统进行以下更改。如果您已经在使用 Antora 3.0，请跳过此部分，转到升级 Node.js。

您是否在使用活跃的 LTS 版本的 Node.js？: 我们建议升级到最新的活跃长期支持（LTS）版本的 Node。Antora 3 正式支持 Node.js 16 LTS 和 Node.js 18 LTS。Antora 3 不支持已经终止支持的 Node.js 版本。请参阅升级 Node.js 获取说明。
您是否已更新 AsciiDoc 语法和 Asciidoctor 扩展以符合最新的 Asciidoctor.js 2.2 补丁版本？: Antora 3 不再支持 Asciidoctor.js 1.5.9（提供 Asciidoctor 1.5.8），现在依赖于最新的 Asciidoctor.js 2.2 补丁版本（提供 Asciidoctor 2.0.x）。Asciidoctor 2 对现有功能引入了一些实质性的更改，可能会影响您的文档源内容或用户界面。请参阅Asciidoctor 升级说明了解受影响的功能以及在升级到 Antora 3 之前应采取的建议措施。
您是否在链接附件文件？: 在 Antora 3 中，已弃用使用 AsciiDoc 链接宏（link:[]）和在目标值中使用 {attachmentsdir} 属性引用附件。将链接宏替换为 xref 宏，并使用附件的资源 ID 来引用它。请参阅附件和导航文件中的附件交叉引用，了解有关 attachment$ 系列坐标的信息和用法示例。
您的组件版本中是否有未版本化的部分？: 我们已经弃用将值 master 分配给 version 键以标识未版本化组件。在 Antora 3 中，将波浪符号（~）分配给组件版本的 antora.yml 文件中的 version 键，以指定其为未版本化。请参阅定义无版本组件了解更多信息。
在交叉引用页面或分配 page-aliases 值时，您是否使用文件扩展名？: 如果在 xref 宏中的资源 ID 或分配给 page-aliases 属性的值中缺少 .adoc 文件扩展名，Antora 2 会在运行时自动将 .adoc 添加到资源 ID 中。由于 xref 宏现在可以引用其他非 AsciiDoc 资源，因此已弃用此回退机制。请检查您的 xref 和 page-aliases 属性中的资源 ID，确保指定了 .adoc 扩展名。
您是否依赖于播放书中的默认分支模式？: 以前的默认分支模式 [master, v*] 已被弃用，并替换为 [HEAD, v{0..9}*]。在使用远程存储库时，这不太可能导致更改。对于本地存储库，可能会导致工作树在以前未使用的情况下被使用。
您是否使用 antora-lunr 插件将 Lunr 集成到您的站点中？: antora-lunr 插件是为 Antora 2 设计的，是一个由社区维护的项目。在 Antora 3 中，antora-lunr 已被 Antora Lunr 扩展（包： @antora/lunr-extension）取代，这是一个官方 Antora 项目。该扩展使用 Antora 3 中的新扩展功能将 Lunr 集成到您的站点中，而无需使用自定义站点生成器。我们鼓励您在升级到 Antora 3 时从 antora-lunr 迁移到 Antora Lunr 扩展。
您是否使用或维护自定义站点生成器？: 在 Antora 3 中，站点生成器必须将 @antora/logger 包声明为依赖项。CLI 会相对于站点生成器解析记录器。如果找不到记录器，它将退回到 CLI 提供的记录器。这可能导致 Antora 配置错误的记录器，用户将看到有关记录器未配置的警告。

还请注意，generateSite 函数的推荐签名已更改。该函数现在接受一个参数，即播放书。旧的签名仍受支持，但使用它将导致播放书被构建两次。

站点生成器还应依赖于 @antora/file-publisher 包，而不是 @antora/site-publisher，尽管从技术上讲这并非必需。
您是否使用自定义 git 凭据管理器？: Isomorphic-git 不再包含 cores（插件）API，因此调用 git.cores.create('antora').set('credentialManager', customCredentialManager) 将失败。Antora 仍然支持 cores API，但用于注册凭据管理器的调用现在负责创建它（因为它在 Antora 加载之前运行）。请参阅配置自定义凭据管理器获取最新说明。

升级 Node.js（可选）

您可以使用任何活跃的 LTS 或维护 LTS 版本的 Node.js 与 Antora，但我们建议使用最新的活跃 LTS 版本，以便从最新的性能和安全增强中受益。 Node.js 发布计划显示了活跃的 Node.js LTS 版本。

要检查您安装了哪个 Node.js 版本，请打开终端并运行：

$ node --version

如果需要升级到活跃的 Node.js LTS 版本，请运行：

Linux 和 macOS

$ nvm install --lts

Windows

$ nvm install 16.20.2

接下来，要将最新版本的 Node.js 设置为任何新终端的默认版本，请运行：

Linux 和 macOS

$ nvm alias default 16

Windows

$ nvm alias default 16.20.2

现在您已准备好升级到最新版本的 Antora。

本地升级 Antora

如果您已在本地安装 Antora，则将使用 package.json 来管理版本。该文件跟踪您当前安装的 Antora 版本。您可以使用该文件指定不同的版本。npm i 命令将查阅此文件以确定要安装的软件包及这些软件包的版本。

切换到包含您的 Antora playbook 文件（例如 antora-playbook.yml）的播放书项目。
打开 package.json 文件。

更改 CLI 和站点生成器的版本号。

{
  "devDependencies": {
    "@antora/cli": "3.1.7",
    "@antora/site-generator": "3.1.7"
  }
}

除非您安装预发布版本，我们建议仅指定主要.次要版本号，以便获得最新的补丁更新。

保存文件。
（可选）删除 node_modules 文件夹和 package-lock.json 文件。尽管删除 node_modules 文件夹并非总是必需，但这样做可以确保您获得全新的安装。如果您至少使用 npm 8，通常不需要执行此步骤。
通过运行 npm i 命令升级站点生成器。
```
$ npm i
```

您现在已经升级到最新版本的 Antora。

作为删除 node_modules 文件夹的替代方法，您可以使用 npm upgrade，这几乎与全新安装相同。

全局升级 Antora

如果您已经全局安装了 Antora CLI 和站点生成器，您可以通过重新安装这些软件包来升级它们：

在终端中运行以下命令：

$ npm i -g @antora/cli@3.1 @antora/site-generator@3.1

npm i 命令将删除任何同名的现有软件包并重新安装它们。

我是否已全局安装了 Antora？

要列出您全局安装的 Node.js 软件包，请在终端中输入以下命令：

$ npm ls -g --depth=0

如果您已经全局安装了 Antora CLI 和站点生成器，您将在终端输出中看到它们以及它们的版本号。

全局安装的 Node.js 软件包列表

/home/user/.nvm/versions/node/v16.20.2/lib
├── @antora/cli@3.1.7
├── @antora/site-generator@3.1.7
├── npm@8.19.4
└── ...

了解更多

查看 Antora 的最新功能和潜在的破坏性更改。