Compose Navigation Files

You can include one navigation file into another using the AsciiDoc include directive. The target of the include directive must be a file that Antora classifies, meaning it must either be a page or a partial. (Antora does not classify files located at the root of the module or in the modules folder).

Let’s assume that one of the navigation lists is defined in the file modules/ROOT/partials/getting-started.adoc.

You can include this partial nav file into the main nav file, modules/ROOT/nav.adoc, as follows:

The Getting Started list will be read from the partial file and included in the navigation after the Overview list.

In some circumstances, you aren’t sure where the the partial list will be included in the navigation tree, and you cannot assume it’s being added at the top level. What you want is for the navigation list from the include to be a level below the current list item.

In order to accomplish this layout, you wrap the included list in an open block:

Antora will recognize this relationship and fuse the included list as a child of the list item to which it is attached. (The open block container is discarded).

Let’s assume that the getting started items are defined in the modules/ROOT/partials/getting-started.adoc file as an anonymous list.

Now we can include this list as a child of a Getting Started item in the main nav file.

The list items from the partial file will be children of the Getting Started item.