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.
Let’s take a brief look at each of the numbered items in this diagram.
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.
Navigation registration (Source)
Navigation files are registered in a component version descriptor file under the
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.
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.
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.
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.
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.