Navigation Files and Lists

All of the source files that belong to a component version’s pages family are automatically published to your site by Antora. That means visitors can find a page using search tools, links on other site pages, and in some scenarios, through dropdown menus such as the page version selector. In order for visitors to locate and go to a page using a component version page menu, a cross reference targeting that page must be entered into a list in a navigation file.

What’s a navigation file?

A navigation file is one or more lists of page cross references, external URLs, and other content that is marked up in AsciiDoc and stored at the base of a module directory. If registered in an antora.yml file, the contents of the navigation file will be incorporated into a component version page menu and published to a site.

Filename and format

Navigation files must end with the AsciiDoc file extension (.adoc). They’re typically named nav.adoc; however, you can use any name that is meaningful to you. Name your navigation files kaboom.adoc if that makes your team happy.

List structure

A navigation list is an unordered AsciiDoc list. Each top-level list item can nested items up to level five (*****).

Example 1. Single list structure

* Top level item
** Second level item
*** Third level item
*** Third level item
** Second level item
*** Third level item
**** Fourth level item
***** Fifth level item
* Top level item
* Top level item

A top-level list item is a list title, which is denoted by a dot (.), or, when there isn’t a list title, each list item that’s marked by a single asterisk (*). When a file contains multiple lists, each list must be initiated with a list title.

Example 2. Multiple list structure

.List title and top level item
* List item

.List title and top level item
* List item
** List item

If a navigation file only contains one list, a list title is optional. In a single list navigation file, each item with a single asterisk marker (*) effectively becomes a top-level item.

You can compose your navigation by combining files using the include directive. Each included file must be located in a partials directory. If you want the navigation list in the included file to be added as a child of the current item, you should enclose the include directive in an open block. Refer to the Compose Navigation Files page to learn how to build the navigation from multiple files.

List titles and items

List titles and items in a navigation file can contain several types of content, such as cross references to pages, links to external sites, and regular and formatted text. The most common items in a navigation file are xrefs to pages that belong to the same component version and module, but a target page ID can be for pages in other modules and components, too.

.The Special Project (1)
* xref:index.adoc[] (2)
** xref:ROOT:get-started.adoc[] (3)
** xref:team::contributing.adoc[] (4)

._Support_ (5)
* https://support.project.com[Get Help] (6)
* xref:help.adoc[*Troubleshooting*] (7)

1	Regular, unlinked text.
2	Xref to a page that belongs to the same module as the navigation file. Antora will apply the target page’s default navigation link text when the site is generated.
3	Xref to a page that doesn’t belong to the same module as the navigation file.
4	Xref to a page that doesn’t belong to the same component as the navigation file.
5	Unlinked text with inline formatting.
6	Link to an external website.
7	Xref with formatted link text.

List items can reference attachments, too.