组件版本如何排序

在本页面中,您将学到:

  • Antora如何对组件和组件版本进行排序。

  • Antora如何选择组件的最新版本。

了解Antora如何对组件版本进行排序在选择版本方案以及在站点UI中呈现和路由结果时非常重要。

文档组件排序顺序

Antora将组件版本分组为文档组件。内容目录中组件的排序顺序是不确定的。但是,当通过UI模型(site.components)访问文档组件时,它们按照标题的字母顺序进行排序。组件的标题由每个组件版本的antora.yml文件中定义的 标题键定义。如果未设置 标题键,Antora在排序组件时将退回到名称键。在每个组件中,版本根据组件版本排序规则进行排序。

这个经过排序的组件列表通常由UI用于呈现一个菜单小部件,读者可以使用它在不同的组件和版本之间导航。Antora的默认UI提供了这样的小部件。在默认UI中,给定组件的版本列表显示在每个组件标题下方。

Antora不要求以这种顺序显示组件和版本。如果您希望它们以不同的顺序显示,您需要自定义生成此列表的UI模板。在自定义Antora的默认UI时,您需要编辑位于UI项目中的src/partials/nav-explore.hbs的名为nav-explore的部分。该模板的关键片段是对site.components的迭代:

{{#each site.components}}
...
{{/each}}

Antora的默认UI使用组件在UI模型中存储的顺序。您可以通过将组件列表传递给必须提供的自定义辅助函数来修改此顺序:

{{#each (rearrange site.components 'component-b,component-a'}}
...
{{/each}}

您还可以选择手动为要显示的每个组件创建菜单条目。这种策略还允许您排除某些组件。

版本方案

Antora在排序文档组件的组件版本时只考虑version键的值。分配给version键的值确定组件版本根据其组件标题或名称在组件版本选择器菜单中的顺序。保留的值~null组件版本定义为无版本

方案 有效标识符 示例

语义化

整数
以数字开头并包含至少一个点(.)字符的字符串
v开头,后跟一个数字,并包含至少一个点(.)字符的字符串

30
2.4
v90.3

命名

所有不符合语义方案或保留版本值(~null)的值

edge
z4

无版本

~
null

~

组件版本排序规则

Antora在对组件的组件版本进行排序时应用以下规则:

  1. 如果存在无版本的组件版本和命名版本,则无版本的组件版本将在命名版本之前显示在组件版本选择器菜单中。

  2. 如果存在组件的命名版本和语义版本,则组件的命名版本将在语义版本之前显示在组件版本选择器菜单中。

  3. 组件的命名版本按照字母顺序逆向排序(例如,z4wishlester)。

    1. URL中不推荐使用带有大写字母的版本标识符,可能会导致在Web服务器之间的可移植性。如果使用大写字母,它们将出现在小写字母之前(例如,Aa)。

  4. 组件的语义版本在组件版本选择器菜单中显示在命名版本之后,如果两者都存在。

  5. 组件的语义版本按降序排序

    1. 语义标识符中的前导v将被忽略,并根据v后的第一个数字进行排序。

    2. 应用语义版本排序规则

确定组件的版本顺序

假设组件RoseyDB包含多个组件版本。一些版本使用语义方案:v2.54.03.9。一些是命名的:utopiavivid。根据Antora的排序规则,RoseyDB组件版本将按照下面列出的顺序在参考UI中显示。

排序后的RoseyDB组件版本
vivid
utopia
4.0
3.9
v2.5

请注意,如果在组件版本的antora.yml文件中定义了display_version键,则将显示display_version的值,而不是version键的值。无论是否设置了display_version,组件版本始终根据分配给其version键的值进行排序。因此,对于读者来说,版本可能看起来并不按照描述的顺序排序。

例如,如果RoseyDButopia版本分配了display_version值为3.0RoseyDB版本仍将按相同顺序排序。在参考UI中,utopia版本只是标记为3.0

vivid
3.0
4.0
3.9
v2.5

Antora还确定每个组件的最新组件版本。对于RoseyDB,最新版本将是vivid,因为它是排序列表中的第一个版本,并且未定义为预发布版本。

最新组件版本

除了对组件版本进行排序外,Antora还识别每个组件的最新稳定版本。最新组件版本,也称为最新版本,是排序列表中第一个不是预发布版本的版本。如果所有版本都是预发布版本,则选择列表中的第一个预发布版本。未标记版本的组件版本始终被视为最新版本或最新预发布版本(如果设置了prerelease)。

当无法确定版本坐标或无法确定版本时,Antora在从另一个组件对传入资源ID引用进行资格验证时使用组件的最新版本。

最新版本可作为UI模型中的latest属性获得。