Register Navigation Files

On this page, you’ll learn:

  • The purpose of the component descriptor nav key.

  • How to register navigation files in a component descriptor.

  • How registration order affects the component menu.

The component descriptor nav key

The navigation key (nav) is set in the component descriptor file (antora.yml) of a component. The nav key accepts a list of navigation files. Each value specifies the path to an individual navigation file.

Component descriptor with two registered navigation files
name: component-b
title: Component B
version: '1.0'
nav: (1)
- modules/ROOT/nav.adoc (2)
- modules/module-one/nav.adoc (3)
1 Navigation key
2 Value registering a navigation file located in the ROOT module
3 Value registering a navigation file located in a module named module-one

When a file is assigned to the nav key, this file is registered. Only the contents of registered navigation files are assembled into and published as a component navigation menu.

The nav key must be entered on its own line be directly followed by a colon (:). Don’t indent the nav key or its list of values.

Navigation values must be structured as follows:

  • Each nav key value must be entered on its own line.

  • Each nav key value must start with a hyphen (-) and then a single blank space.

  • Following the single blank space, enter the path to an individual navigation file relative to the location of the component descriptor file.

In this example, two navigation files have been registered.

name: component-b
title: Component B
version: '1.0'
nav:
- modules/ROOT/nav.adoc
- modules/module-one/nav.adoc

The navigation lists in these two files will be published into a single component menu for Component B 1.0.

How registration order affects the component menu

The order of the nav key values dictates the order the contents of the navigation files are assembled in the published component menu. In the case of the example from the previous section, the contents of the ROOT navigation file will be at the top of the component menu and the contents of the Module One navigation file will be appended to the end of the ROOT navigation list.

What’s next?

Learn all about creating navigation lists and navigation items: