Navigation Assembly

With Antora, you can create your site’s navigation with AsciiDoc and store it right alongside your documentation files.

The navigation for an Antora documentation site requires:

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

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

  • a UI bundle, such as the Antora default UI, that can apply styles and interaction behavior to the menu(s) Antora generates.

Antora navigation assembly diagram showing the required source files and the resulting site 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.

The navigation for a component is described by at least one AsciiDoc file. However, as seen in the diagram, you can have as many navigation files as you need. Creating a navigation file per module is a common organizational structure we see.

A navigation file contains one or more AsciiDoc lists. Each item in a list can be the link to a documentation page, URL to a website that isn’t part of the site, or unlinked content such as a category title that groups a nested set of links. Documentation page links are created using the same cross referencing syntax used in the pages themselves.

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

Navigation files are registered in a component descriptor file under the nav key (nav). List the navigation files in the order you want them to be displayed in when they’re published to the component menu on your site. When you run Antora, it will only use the registered navigation files to create the component menu.

three Component navigation 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 navigation menu for the component to the site. The behavior and style of the menu is dictated by the UI bundle specified in your playbook.

Screenshot of the component navigation menu in an Antora documentation site

Antora carries out this assembly process for each version of each component that it locates in the repositories, branches, and tags listed under sources in the site’s playbook.

four Component version selector (Site)

When your site has several components and several versions of one or more components, Antora assembles an aggregated list of the components and their versions. We refer to this master menu of components and versions as the component version selector. Antora automatically lists the components in alphabetical order and the versions in order from the greatest or latest.

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

In the default UI, this list is displayed in the “drawer” located at the bottom of any component menu. When a visitor clicks on the drawer, it expands upwards and the reader can then select the component and 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. From this selector, a visitor can navigate between other versions of that page. Antora automatically populates this selector menu when multiple versions of a page are available.

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

What’s next?

Summit Stats: All the details about each concept.