创建具有多个列表的导航文件

结构化多个列表

导航文件可以包含多个无序的AsciiDoc列表。当导航文件包含多个列表时：

  • 每个列表必须以列表标题开头，且

  • 每个列表之间必须至少用一个空行分隔。

.列表标题 (1)
* 列表项
(2)
.第二个列表标题 (3)
* 列表项 (4)
1 必需的列表标题。列表标题前面带有一个点（.）。在标题的.和内容之间不能有空格。
2 列表之间需要空行。
3 必需的列表标题。
4 列表项。

转换为HTML后，列表标题变为顶级项目，所有列表项按照层级顺序嵌套在其下。列表之间的空行在发布的菜单中不会显示。

每个导航列表由列表项组成。

示例1. 包含多个列表的导航文件 
.列表标题 (1)
* 列表项 (2)
* 列表项 (3)
** 嵌套项 (4)

.列表标题 (5)
* 列表项
** 嵌套项

.列表标题
* 列表项
1 列表标题成为列表的顶级项目。
2 列表项前面带有无序的AsciiDoc列表标记（*）。
3 每个列表项必须单独占据一行。
4 在标记的最后一个星号和列表项内容之间加入一个空格。
5 列表标题，表示另一个导航列表的开始。

每个列表项前面带有标记。无序的AsciiDoc列表的标记可以是一个星号（*）到五个星号（*****）。

创建包含两个列表的导航文件

让我们创建一个包含两个导航列表的导航文件，用于模块中的页面。导航列表中最常见的项目是指向与导航文件相同模块的页面的交叉引用xrefs。下面的练习假设导航文件将属于与其引用的页面相同的组件版本和模块。这意味着资源ID不需要指定版本、组件或模块坐标。

  1. 在文本编辑器或您选择的IDE中打开一个新文件。

  2. 在第一行输入一个点（.），紧接着是xref宏前缀和目标页面的资源ID。

    .xref:get-started.adoc

  3. 在资源ID的末尾，用一对方括号（[]）完成宏。按Enter键转到下一行。

    .xref:get-started.adoc[]

    由于方括号内没有指定链接文本，Antora在生成站点时将使用目标页面的默认链接文本的值。

  4. 让我们添加一个列表项。输入一个星号（*），后面是一个空格，然后是一个xref。这次，在方括号内输入链接文本。按Enter

    .xref:get-started.adoc[]
* xref:install.adoc[安装设置和步骤]

    链接文本安装设置和步骤将显示在组件版本页面菜单中。

  5. 让我们开始一个新列表。按Enter键在列表之间插入一个空行。在新行上，输入一个点（.），后面是常规文本。这个列表标题不会引用页面。

    .xref:get-started.adoc[]
* xref:install.adoc[安装设置和步骤]

.CLI命令和选项

  6. 在下一行，输入一个星号（*），一个空格，然后是xref宏。这个项目是一个交叉引用，将使用目标页面的默认链接文本。

    .xref:get-started.adoc[]
* xref:install.adoc[安装设置和步骤]

.CLI命令和选项
* xref:commands.adoc[]

  7. 最后，在前一个项目下嵌套一个列表项。输入两个星号（**），后面是一个空格，然后是xref。

    .xref:get-started.adoc[]
* xref:install.adoc[安装设置和步骤]

.CLI命令和选项
* xref:commands.adoc[]
** xref:commands-in-action.adoc[]

  8. 将文件保存为nav.adoc，保存在包含列表中引用页面源文件的模块目录中。导航文件应该位于与pages目录相同层级的位置。不要将其保存在pages文件夹中！

    📂 modules
  📂 a-module
    📂 pages
    📄 nav.adoc

    您也可以根据需要保存文件，只要扩展名为.adoc即可。

您现在已经为一个模块创建了一个导航文件！确保您在antora.yml中注册它，以便它成为组件版本页面菜单的一部分。