导航文件和列表

所有属于组件版本的pages系列的源文件都会被Antora自动发布到您的站点上。这意味着访问者可以使用搜索工具、其他站点页面上的链接以及在某些情况下,通过下拉菜单(如页面版本选择器)找到页面。为了让访问者能够通过组件版本页面菜单找到并访问页面,必须在导航文件中的列表中输入指向该页面的交叉引用。

什么是导航文件?

一个导航文件是一个或多个页面交叉引用、外部URL和其他内容的列表,使用AsciiDoc标记,并存储在模块目录的基础部分。如果在antora.yml文件中注册,导航文件的内容将被合并到组件版本页面菜单中,并发布到站点上。

文件名和格式

导航文件必须以AsciiDoc文件扩展名(.adoc)结尾。它们通常被命名为nav.adoc;但是,您可以使用任何对您有意义的名称。如果使用kaboom.adoc这样的名称让您的团队开心,那就使用它。

列表结构

导航列表是一个无序的AsciiDoc列表。每个顶级列表项可以嵌套到第五级(*****)。

示例1. 单个列表结构
* 顶级项目
** 第二级项目
*** 第三级项目
*** 第三级项目
** 第二级项目
*** 第三级项目
**** 第四级项目
***** 第五级项目
* 顶级项目
* 顶级项目

顶级列表项是一个列表标题,用点号(.)表示,或者当没有列表标题时,每个由单个星号(*)标记的列表项。当一个文件包含多个列表时,每个列表必须以列表标题开头。

示例2. 多个列表结构
.列表标题和顶级项目
* 列表项

.列表标题和顶级项目
* 列表项
** 列表项

如果导航文件只包含一个列表,则列表标题是可选的。在单个列表导航文件中,每个带有单个星号标记(*)的项目实际上成为一个顶级项目。

您可以通过使用include指令组合文件来构建导航。每个包含的文件必须位于partials目录中。如果希望将包含文件中的导航列表添加为当前项目的子项目,应将include指令包含在一个开放块中。查看组合导航文件以了解如何使用多个文件和include指令创建导航列表。

列表标题和项目

导航文件中的列表标题和项目可以包含多种类型的内容,例如页面的交叉引用、外部站点的链接以及常规和格式化文本。导航文件中最常见的项目是指向同一组件版本和模块的页面的交叉引用,但目标资源ID也可以是其他模块和组件中的页面。

.特殊项目 (1)
* xref:index.adoc[] (2)
** xref:ROOT:get-started.adoc[] (3)
** xref:team::contributing.adoc[] (4)

._支持_ (5)
* https://support.project.com[获取帮助] (6)
* xref:help.adoc[*故障排除*] (7)
1 常规、未链接的文本。
2 指向与导航文件相同模块的页面的交叉引用。当生成站点时,Antora将应用目标页面的默认导航链接文本
3 指向与导航文件不同模块的页面的交叉引用。
4 指向与导航文件不同组件的页面的交叉引用。
5 带有内联格式的未链接文本。
6 链接到外部网站
7 带有格式化链接文本的交叉引用。

列表项也可以引用附件