Navigation Assembly

With Antora, you can create a component version’s navigation with AsciiDoc and store it alongside your source files.

Navigation assembly requirements

The navigation for a site requires:

  • at least one navigation file that contains at least one unordered AsciiDoc list,

  • at least one navigation file registered in the component version descriptor file, and

  • a UI bundle, such as Antora’s reference UI, that can apply styles and interaction behavior to the menus Antora generates.

Antora navigation assembly diagram showing the required source files and the resulting menus where the content from the source files is displayed

Let’s take a brief look at each of the numbered items in this diagram.

one Navigation files (Source)

The navigation for a component version is described by at least one AsciiDoc file. However, as you can see in the diagram, you can assemble a component version’s navigation from multiple files. Creating a navigation file per module is a common organizational structure, but it isn’t required.

A navigation file contains one or more bulleted lists. Each item in a list can be the cross reference to a page, URL to a website that isn’t part of the site, or unlinked text such as a category title that groups a nested set of list items. You can compose the navigation from multiple files.

When you want the contents of a navigation file to be published to a component version’s page menu, you need to register the file in the corresponding component version descriptor file.

two Navigation registration (Source)

Navigation files are registered in a component version descriptor file under the nav key. List the navigation files in the order you want them to be displayed in the published component version page menu on your site. When Antora runs, it only uses the registered navigation files to create the component version page menu.

three Component version page menu (Site)

Antora collects the contents of each registered navigation file, puts the contents in the order the files are listed under the nav key, and publishes a fully assembled menu of pages for the component version. The behavior and style of the component version page menu is dictated by the UI bundle specified in your playbook.

Screenshot of the component version page menu in an Antora documentation site

four Component version selector (Site)

When your site has several components and/or component versions, Antora assembles an aggregated list of the components and their versions. This master menu of components and their component versions is the component version selector. Antora automatically lists the components in alphabetical order. Each component version is ordered from the greatest or latest.

Screenshot of the component version selector dropdown menu in an Antora documentation site

In the reference UI, this list is displayed in the “drawer” located at the bottom of any component version page menu. When a visitor clicks on the drawer, it expands upwards and the reader can then select the component version they want to see.

five Page version selector (Site)

If a page is available in more than one version of a component, a dropdown selector is visible on that page in the reference UI. From this selector, a visitor can navigate between other versions of that page. Antora automatically populates this selector when multiple versions of a page are available.

Screenshot of the page version selector dropdown menu in an Antora documentation site