Navigation File Locations

A common pattern is for each module directory to contain its own navigation file. Modules already represent logical groups of concepts or objectives, so it’s likely that you’d arrange the xrefs to that module’s pages into a continuous, hierarchical flow of navigation menu entries. This also reduces the number of coordinates the page IDs in the xrefs require when you add a page to the navigation file.

Navigation files should be stored at the base of a module directory, i.e., at the same level as a pages family directory. Don’t save navigation files inside a pages folder, otherwise the navigation files will be converted to pages and published as pages.

A module directory can contain more than one navigation file. This functionality helps you finely tune the navigation list order when you register the navigation files in an antora.yml file.

Storing a navigation file in the module it references simplifies the page cross references entered into it. It also helps writers locate the navigation that’s affected when they add pages to or remove pages from a module. However, xrefs to other modules' pages (and even other component versions' pages) can be entered into any module’s navigation file. You just need to add the module coordinate (or component name and version coordinates) to the cross references you create in the navigation file. For example, you could store a single navigation file in a component version’s ROOT module, and, instead of having navigation files in each module in the component version, you could just add the cross references to pages in those other modules directly to the ROOT module’s navigation file.