Antora CLI命令
本页面向您介绍Antora CLI以及您如何使用它来配置和运行Antora。
什么是Antora CLI？
Antora命令行界面（Antora CLI）是一个简单的工具（命名为antora），它使您能够从终端应用程序的命令提示符中执行并可选配置Antora和任何已注册的扩展组件和扩展。
Antora的CLI是Antora的主要用户界面入口点。因此，在文档中经常会看到它被推荐作为与Antora交互的推荐方式。
| 如果您不熟悉命令行，CLI入门提供了命令解剖、导航工作目录和终端应用程序概念的基本概述。 |
默认情况下，Antora会在提供的playbook中查找其配置设置。当使用Antora CLI时，您可以根据需要使用CLI选项或环境变量指定可选配置覆盖。
用法
当您与CLI交互时，您会在终端应用程序的提示符中输入命令，然后按Enter键执行它。命令由程序名称（或程序路径）后跟零个或多个选项和参数组成。在接下来的几节中，我们将分解Antora CLI的这些部分。
| 对于某些程序，如Antora，命令也可以指代程序的主要参数。这可能会令人困惑，因为您会看到术语命令用于表示两个不同的概念。一个是您在提示符中键入的整个命令，另一个是程序的主要参数。 |
每个命令都以基本调用（即程序名称或路径）开头。
$ antora
在Antora CLI的情况下，基本调用是antora。这假定Antora CLI在PATH中可用（例如，全局安装）。否则，基本调用必须是antora bin脚本的路径（例如，npx antora）。基本调用必须与任何命令（用于程序）、选项或参数至少相隔一个空格。
如果您运行基本调用而不指定任何命令、选项或参数，如在antora基本调用中所示，您将看到一个用法说明（即，帮助文本）。
$ antora Usage: antora [options] [[command] [args]] 一个用于AsciiDoc的模块化、单个或多个存储库文档站点生成器。 选项: -v, --version 输出CLI和默认站点生成器的版本。 -r, --require <library> 在执行命令之前要求库（也称为节点模块）或脚本。 --stacktrace 如果应用程序失败，则将堆栈跟踪打印到控制台。 -h, --help 输出使用信息。 命令: generate [options] <playbook> 生成指定在<playbook>中的文档站点。 运行'antora <command> --help'以查看命令的选项和示例（例如，antora generate --help）。
|
Windows故障排除
在Powershell中运行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine 另一种替代方法是使用Windows命令提示符运行Antora。 |
用法说明提供了关于antora程序的概述，其中包括：
-
命令语法，
-
描述，
-
全局选项列表，
-
命令列表，以及
-
请求额外帮助的建议。
用法说明以以下提示开始：
Usage: antora [options] [[command] [args]]
这是了解它识别的选项、命令和参数的提示。
命令
Antora CLI支持的命令总结在以下表中。在此上下文中，术语命令指的是antora基本调用接受的主要参数（而不是整个命令）。
| 命令 | 目的 |
|---|---|
|
|
使用指定的playbook文件生成站点。Antora会自动使用默认的Antora流水线运行 |
|
|
输出Antora CLI的使用说明。请注意，此命令不在使用说明中显示。 |
|
|
输出Antora CLI的版本号。请注意，此命令不在使用说明中显示。 |
help和version是显示有关Antora CLI本身信息的元命令。Antora CLI当前仅支持一个功能命令，即generate。由于generate是Antora CLI的主要功能，因此您不必显式指定它。如果未指定命令，则generate命令将始终被隐含（除非单独执行基本调用）。
generate命令
$ antora antora-playbook.yml
您已经了解到如果不存在generate命令，则会被隐含。因此，带playbook参数的antora基本调用等同于带显式命令和playbook参数的antora基本调用中显示的命令。
$ antora generate antora-playbook.yml
让我们分解这个命令：
-
该命令假定Antora CLI在
PATH中可用（例如，全局安装）。否则，需要将antora替换为antorabin脚本的路径（例如，npx antora）。 -
基本调用
antora告诉Antora CLI运行，然后读取剩余的命令和参数。 -
指定的（隐含或显式）命令是
generate。您在带playbook参数的antora基本调用中看不到命令，因为它是可选的，但如果不存在，Antora会暗示它存在。随后的选项和参数适用于命令，因此在这一点上控制权转移到命令。 -
generate命令需要一个明确的参数，指定当前工作目录相对于playbook文件的文件系统路径。在带playbook参数的antora基本调用中，playbook文件的相对文件系统路径是antora-playbook.yml。也就是说，该命令是从存放playbook文件的同一目录执行的。
指定 playbook
无论是隐式还是显式输入的 generate 命令，都需要一个参数来指定相对于当前工作目录的 playbook 文件系统路径。
在下一个示例中，让我们使用一个名为 antora-playbook.yml 的 playbook 文件，该文件位于 home/my-projects/a-project/docs-site。如在命令提示符（$）之前直接显示的那样，在 指定位于工作目录中的 playbook 中，工作目录是 docs-site。这意味着与 antora 和 generate 命令以及 playbook 参数相关的进程将相对于 docs-site 进行解释。由于 playbook 文件 antora-playbook.yml 确实位于工作目录中，因此只需要指定 playbook 的文件名。
docs-site $ antora antora-playbook.yml
当 playbook 不存储在工作目录中时，playbook 参数必须包含相对于工作目录的路径或从文件系统根目录到 playbook 文件的完整路径。
在 指定 playbook 的文件系统路径 中，工作目录是 my-projects。playbook 文件存储在 home/my-projects/a-project/docs-site 中。
my-projects $ antora a-project/docs-site/antora-playbook.yml
在 指定 playbook 的文件系统路径 中，playbook 相对于工作目录的文件系统路径被输入为命令的唯一参数。
Playbook 文件扩展名
不需要指定 playbook 的文件扩展名。只要 playbook 参数包含文件的 stem（例如，antora-playbook），Antora 就会自动检测文件扩展名。
在 自动检测 playbook 文件扩展名 中，playbook 参数没有文件扩展名，因此 Antora 将查找与 playbook 文件 stem 相匹配的文件，相对于工作目录。
docs-site $ antora antora-playbook
Antora 对 playbook 文件格式的搜索顺序是 YAML，然后是 JSON，最后是 TOML。
您可以在 运行 Antora 中查看更多关于 antora 和 generate 命令的示例。 |
显示 Antora CLI 帮助
如果您已经阅读了整个页面，您已经知道如何显示 Antora CLI 的主帮助文本。只需输入 antora 并按 Enter 键。但还有一种更惯用的方法。
在 显示 antora 基本调用的帮助 中的命令将显示 antora 程序的帮助。
$ antora -h
显示帮助的另一种方法是使用隐式的 help 命令：
$ antora help
如在用法说明的结尾建议的那样，您还可以通过在基本调用中包含命令的名称并将 -h 选项放在其后来显示 generate 命令的帮助。
$ antora generate -h
您还可以使用隐式的 help 命令编写此命令：
$ antora help generate
Antora CLI 还支持许多其他选项，这些选项在 CLI 选项 中有介绍。