Compose Navigation Files

If you want to compose a navigation list from various files, perhaps to reuse the lists, organize them so they can be maintained by different people, or simply break them up, you can use the include directive.

Include one navigation file into another

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.

Example 1. modules/ROOT/partials/getting-started.adoc
.Getting Started
* xref:download.adoc[]
* xref:install.adoc[]
* xref:run.adoc[]

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

Example 2. modules/ROOT/nav.adoc
.Overview
* xref:index.adoc[]
* xref:contribute.adoc[]

include::partial$getting-started.adoc[]

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

Include a nested 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, wrap the included list in an open block:

* xref:parent.adoc[]
+
--
include::partial$children.adoc[]
--

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.

Example 3. modules/ROOT/partials/getting-started.adoc
* xref:download.adoc[]
* xref:install.adoc[]
* xref:run.adoc[]

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

Example 4. modules/ROOT/nav.adoc
* xref:index.adoc[]
* xref:contribute.adoc[]
* Getting Started
+
--
include::partial$getting-started.adoc[]
--
* xref:reference.adoc[]

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