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.
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 (
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.
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.
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.
When your site has several components and/or 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.
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.
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.
Summit Stats: All the details about each concept.