Antora工作原理

Antora的站点生成器处理创建文档站点的所有方面，从获取和聚合到转换和排列内容再到发布生成站点的文件。本页面详细描述了这个过程。

默认的流水线是有主见的，可以让您尽快开始。但要理解的是，Antora具有模块化、开放的架构。这意味着这个架构可以通过允许插入自定义的Antora组件（如验证器）来适应专门的用例。本页面侧重于Antora中的核心内置组件和功能。

默认生成器流水线中的步骤

本节列出的步骤描述了站点生成器执行的操作。某些操作是异步执行的，因此下面的一些步骤可能以不同的顺序发生，或同时发生。例如，当内容被聚合时，UI被获取和加载，以优化网络的使用。

构建playbook: 当您准备好生成站点时，您会向Antora传递一个playbook文件并告诉它运行。

一个playbook文件是一个简单的配置文件，可以用YAML、JSON或TOML编写。它包含信息和设置，如要使用的内容、内容应如何处理、站点应如何生成以及要发布输出的位置。

Antora读取playbook文件并从中构建一个playbook，然后用它来驱动流水线。
加载内容存储库: 使用playbook中列出的内容源，Antora加载指定的git存储库或本地内容文件夹，准备扫描这些文件以获取内容文件。

对于每个远程URL，Antora使用内置的git客户端将远程git存储库克隆到本地缓存中。如果已经克隆了存储库，Antora会根据配置获取更新。

最后，Antora确定要从指定存储库中使用哪些引用（分支、标签和起始路径）。
查找内容源根: 从内容源根开始，当找到名为antora.yml的组件版本描述文件时，Antora将一组文件标识为组件版本的一部分。这些源文件可以存储在单个存储库中，存储库的根目录或子路径中，或分布在多个存储库中。
将输入文件转换为虚拟文件对象: Antora从每个内容源根子树中收集所有文件（文本、图像、示例和其他支持材料）。然后它为每个输入文件创建一个虚拟文件。
将文件分配给组件版本桶: Antora读取组件版本描述（antora.yml）文件。

组件版本描述将其下的文件与指定的组件名称和版本（即组件版本）关联起来，使文件能够与其所在的存储库解耦，并使Antora的URL不可知的交叉引用成为可能。

Antora将描述符信息和其他源元数据分配给虚拟文件。然后，根据分配的组件版本数据，将每个文件排序到虚拟集合中。

组件版本通常代表项目、库、服务或培训课程的离散和独特版本的文档。
计算额外的元数据: 使用playbook中的站点属性和前一步中分配给文件的信息，Antora为每个文件添加模块、系列、系列相对路径和其他元数据值。它还为每个可发布文件计算输出路径（磁盘）和发布路径（URL）信息。
将文件组织成内容目录: Antora进一步将聚合的文件分类到可查询和传输的内容目录中。

将AsciiDoc文件转换为可嵌入的HTML: 内容目录中的AsciiDoc文件将使用Asciidoctor.js转换为可嵌入的HTML。
转换导航文件: Antora从内容目录中检索导航文件，将其内容翻译为按指定层次结构组织的导航项（导航树分组在导航菜单内），并返回导航模型。
定位并获取UI包: Antora找到playbook中列出的URL中的UI包并获取它。UI包可以是本地缓存或远程缓存。
将UI文件转换为虚拟文件对象: Antora提取包中的UI文件，并为每个文件创建一个包含文件内容和路径信息的虚拟文件对象。
对UI文件进行分类: Antora使用UI描述符文件（ui.yml）识别静态UI文件，并将文件类型设置为静态。它根据文件位置（资源、布局、助手、部分）为所有其他文件设置类型。
计算UI文件的输出路径: 对于每个可发布的UI文件（静态或资源类型），Antora计算其输出路径。
将UI文件组织成UI目录: 虚拟UI文件被分类到一个可传输的集合中。
将转换后的AsciiDoc内容包装在页面模板中: Antora确定每个页面请求的页面模板。它使用页面的可嵌入HTML、站点元数据、页面的上下文数据（组件、版本）以及页面、版本和产品选择器的导航模型信息填充已识别的UI模板，用于菜单和面包屑。

依靠页面模板生成页面使站点所有者完全控制页面的构建，从而完全控制UI。
生成站点地图: Antora生成一个站点地图，可用作内部报告或与站点一起发布。这个站点地图按组件名称（使用站点地图索引）进行分区。站点地图索引链接到每个组件名称的站点地图，其中可以找到各个页面的URL。
发布站点: Antora将生成的页面写入默认或用户指定的位置。站点可以以多种格式发布到多个位置，使用内置和自定义目标提供程序通过多个协议。

可以用自定义生成器替换默认站点生成器。您首先需要创建一个库或脚本，导出带有签名generateSite(args, env)的函数。在该脚本中，您可以自由地从Antora导入核心组件以重新组装自己的流水线。然后，通过将库或脚本的名称传递给Antora CLI的--generator选项来激活您的流水线。