Single List and Multi-list Navigation Files

On this page, you’ll learn:

  • The AsciiDoc list type (unordered) that navigation files require.

  • How to nest list items at different hierarchy levels.

  • How list titles affect item hierarchy and the number of lists a navigation file can contain.

  • How to construct a single list navigation file.

  • How to construct a navigation file that contains several lists.

Unordered AsciiDoc lists

A navigation file can contain one or more unordered AsciiDoc lists. An unordered list contains one or more list items. A list item is preceded by a marker. In the case of an unordered list, the marker is at least one asterisk (*). Each list item must be entered on its own line. Blank lines and comment lines can be interspersed between the list items.

List item nesting

The top-level list item in a navigation list is marked by a single (*). Each top-level item can have as many nested items as you need. The greatest nesting depth allowed is level five (*****).

Item level syntax
* Level 1 (top)
** Level 2
*** Level 3
**** Level 4
***** Level 5

List titles

You can also add list titles to your navigation lists. A title is preceded by a period (.). Unlike list items, there must be no spaces between the . and the content of the title.

List title syntax
.List title
* List item
* Another list item

When converted into a component navigation menu, list titles become level one list items with all other item levels (* through *****) getting nested beneath them.

A list title is optional when a navigation file only contains one list. If a navigation file contains multiple lists, each list in that file must have a title.

Single list file

When a navigation file only contains one list, a list title is optional.

Single list structure and syntax
* List item
** Nested item

* List item
// Comment line
* List item
** Nested item
*** Nested item

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 navigation menu, and the comments aren’t visible to site visitors.

Multi-list file

When a navigation file contains multiple lists, each list must have a title and be separated by at least one blank line.

Multi-list structure and syntax
.List title        (1)
* List item
                   (2)
.Second list title (3)
* List item
** Nested item
*** Nested item
1 Required list title
2 Required blank line between lists
3 Required list title

When converted to HTML, the list titles become top level items and all of their list items are nested under them in cascading order. The blank line between the lists is not present in the published menu.

What’s next?

Learn all about creating and formatting navigation list items:

Learn how to register navigation files so they get included in a component menu: