Create a Navigation File with One List

Single list structure

A single list navigation file contains one unordered AsciiDoc list. An unordered list is made up of list items.

* List item (1)
* List item (2)
** Nested item (3)
(4)
* List item
// Comment line (5)
* List item
** Nested item (6)
*** Nested item

1	List item preceded by an unordered AsciiDoc list marker (`*`).
2	Each list item must be entered on its own line.
3	Enter a blank space between the last asterisk of a marker and the content of your list item.
4	List items can be interspersed by blank lines.
5	List items can be interspersed by comment lines.
6	A nested list item.

Each list item is preceded by a marker. An unordered AsciiDoc list’s marker can range from one asterisk (*) to five asterisks (*****).

You can separate list items with blank lines or comment lines. The blank lines are removed from the HTML when the list is published as a component version page menu, and the comments aren’t visible to site visitors.

Top-level list items and nesting

The top-level list item in a single list navigation file is marked by either a single asterisk (*) or, when the first item is a list title, a dot (.). A list title is optional. Unlike list items, there must be no spaces between the . and the content of the title.

.List title (1)
* List item
* Another list item
** A nested list item

1	A list title becomes the top-level item for the entire list.

When converted into a component version page menu, the list title becomes the top-level item for all of the other list items (* through *****) in that file. Therefore, all of the other list items will be nested beneath the title.

When a list doesn’t have a title, each item with a single asterisk marker (*) becomes a top-level item to any list items that are nested directly under it.

* List item (1)
** A nested list item (2)
* Another list item (3)

1	A top-level list item.
2	This list item is nested under the preceding top-level list item.
3	A top-level list item.

The greatest nesting depth allowed is level five (*****). Each list item can have as many nested items as you need.

Create a single list navigation file

Let’s create a navigation file named nav.adoc that defines a single navigation list for the pages in a module. The most common items in a navigation list are xrefs to pages that belong to the same module as the navigation file. The exercise below assumes that the navigation file will belong to the same component version and module as the pages it is referencing. That means the page IDs won’t need to specify version, component, or module coordinates.

Open a new file in the text editor or IDE of your choice.
On the first line, type an asterisk (*), directly followed by a blank space. Then type an xref macro prefix and the page ID of the target page.
```
* xref:get-started.adoc
```
At the end of the page ID, complete the macro with a set of square brackets ([]). Press kbd:[Enter] to go to the next line.
* xref:get-started.adoc[]
Since there isn’t any link text specified inside the square brackets, Antora will use the value of the target page’s default link text when it generates the site.
Let’s add a nested list item. Type two asterisks (**), followed by a blank space, and then an xref. This time, enter link text inside the set of square brackets ([]).
* xref:get-started.adoc[] ** xref:install.adoc[Installation Setup and Steps]
The link text, Installation Setup and Steps, will be displayed in the component version page menu.
Let’s create another top-level item that’s only text, i.e., it isn’t a page reference. On the next line, type an asterisk (*), a blank space, and then your text.
```
* xref:get-started.adoc[]
** xref:install.adoc[Installation Setup and Steps]
* CLI Commands and Options
```
Now, nest a list item under the previous top-level item. This item is a cross reference that will use the target page’s default link text.
```
* xref:get-started.adoc[]
** xref:install.adoc[Installation Setup and Steps]
* CLI Commands and Options
** xref:commands.adoc[]
```

Finally, nest a list item under the previous item. Type three asterisks (***), followed by a blank space, and then an xref.

* xref:get-started.adoc[]
** xref:install.adoc[Installation Setup and Steps]
* CLI Commands and Options
** xref:commands.adoc[]
*** xref:commands-in-action.adoc[]

Save the file as nav.adoc in the module directory that contains the page source files referenced in the list. The navigation file should be located at the same hierarchy level as the pages directory. Don’t save it in the pages folder!
📂 modules 📂 a-module 📂 pages 📄 nav.adoc
You can also save the file with the filename of your choice, as long as the extension is .adoc.

You’ve now create a navigation file for a module! Make sure you register it in antora.yml so it becomes part of the component version page menu.