Navigation

This content was generated with the assistance of AI and should be verified against the official documentation of each tool before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

The navigation of an Antora site is not derived from the directory layout. It is written by hand in AsciiDoc files that are registered in the component version descriptor, and Antora assembles them into the page menu shown on every page of that component version. This page explains how those files are written, registered and composed. It was written against Antora 3.2.1 and checked on 2026-10-26. The examples use Pocket Units, a tiny units-conversion library with a ROOT module and a guides module, and were built with Antora 3.2.1 and the Antora Default UI.

What a navigation file is

A navigation file is an AsciiDoc file that contains, or includes, one or more unordered lists. Each list item is a page cross reference, an external URL or plain text. Nesting the items builds the tree that the UI renders as the menu. Antora reads only the files that are registered under the nav key of the component version’s antora.yml. A file named nav.adoc that is not registered is ignored. Navigation is per component version: every version of a component has its own menu, and a page that belongs to no list is still published and reachable, it just has no menu entry.

Navigation files live at the base of a module directory, next to the pages family directory. They must not be stored inside pages, because everything there is published as a page. The usual layout is one file per module, which keeps the xrefs short because they are resolved relative to the module that holds the file.

modules/
  ROOT/
    nav.adoc
    pages/
    partials/
  guides/
    nav.adoc
    pages/

A module may also hold several navigation files, and a file may be kept in one module while linking to pages of another, as long as the xrefs carry the module (or component and version) coordinate. See modules and families for the directory layout and resource IDs and xrefs for the coordinate syntax.

Registering navigation files

Registration is done with the nav key of antora.yml. Its value is a list of paths relative to the antora.yml file. The order of the list is the order of the menu: Antora appends the contents of each file after the previous one.

antora.yml
name: pocket-units
title: Pocket Units
version: '2.0'
asciidoc:
  attributes:
    product-name: Pocket Units
nav:
- modules/ROOT/nav.adoc
- modules/guides/nav.adoc

Source: Antora docs: Register Navigation Files

If the latest version of a component has no navigation registered, the component is left out of the component version selector of the default UI. The official documentation does not describe the outcome of listing a path that does not exist, so check the build log after changing the list. The descriptor keys are covered in the component version descriptor page.

List syntax

Items use asterisks, from one * for the top level up to five ***** for the deepest. The official documentation specifies unordered lists for navigation files, so write them with asterisks. The official documentation says lists may be nested at any depth, while the multiple-lists page shows markers up to five asterisks, so keep trees shallow: a menu with more than three levels is hard to read in the default UI anyway.

modules/ROOT/nav.adoc
* xref:index.adoc[]
* xref:getting-started.adoc[]
* Reference
** xref:api.adoc[]
** https://example.org/pocket-units/changelog[Online changelog]

Source: Antora docs: Navigation list

Without a list title, a list is an anonymous top-level list: its items appear at the root of the menu. A file with a single anonymous list is the simplest form and is enough for a small component.

List titles

A block title (a line that starts with a dot, with no space between the dot and the text) in front of a list makes the list a named group. The title becomes a top-level, non-link item of the menu and the items of the list are nested under it. A file may contain several titled lists, separated by blank lines.

modules/guides/nav.adoc
.Guides
* xref:converting-lengths.adoc[]
* xref:custom-units.adoc[]

Source: Antora docs: Navigation files with multiple lists

Titles are the usual way to give each module its own heading, because every registered file contributes its lists to the same menu.

Entries and their text

Page cross references

An entry that links to a page uses the xref macro with the page’s resource ID. When the link text is empty, Antora fills it in, in this order: the navtitle attribute of the target page, then its reference text, which is the reftext attribute or, when that is not set, the page title. When the text is given in the brackets, it wins. The text is used both in the menu and in the breadcrumbs of the target page.

* xref:index.adoc[]
* xref:getting-started.adoc[]
* xref:api.adoc[]
* xref:guides:converting-lengths.adoc[Length conversions]

In the Pocket Units site, index.adoc sets :navtitle: Overview, getting-started.adoc sets :reftext: Quick start and api.adoc sets :navtitle: API Reference. The built menu showed "Overview", "Quick start" and "API Reference", and the last entry showed the explicit text. Setting navtitle is useful when the page title is long, because it shortens only the menu entry. The attribute reference is described in AsciiDoc attributes and extensions.

Antora does not fill in the text of an xref that has a fragment, so the text must be written. The built menu shows the text that was written and links to the fragment of the current page:

** xref:getting-started.adoc#install[Install section]

Source: Antora docs: Xrefs and Link Text

External links

A URL with a scheme becomes an external link. The text in the brackets is optional; without it the menu shows the raw URL.

** https://example.org/pocket-units/changelog[Online changelog]

Source: Antora docs: External links

Non-link entries

Plain text without an xref or a URL is a group label: it is rendered as text with no link and normally holds nested items. The Reference and Downloads items of the example below are non-link entries. The difference with a list title is that a non-link entry can be nested at any level, while a list title is always a top-level heading.

* Reference
** xref:api.adoc[]
** https://example.org/pocket-units/changelog[Online changelog]

Source: Antora docs: Format List Content

Attachments

The family can also be attachment$, which makes the menu entry a download link. When the text is left empty the menu shows the resource ID, so always write the text.

* xref:attachment$units.csv[Unit table (CSV)]
* xref:attachment$pocket-units-sample.zip[Sample project]

Source: Antora docs: Reference resources

The next page, Partials, Examples and Attachments, describes the attachments family in detail.

Composing navigation from several files

Navigation can be composed in two ways: by registering several files (the menu is their concatenation, in nav order) and by including one file into another. Both can be combined.

Several registered files

Registering one file per module is the first form of composition, as in the antora.yml above. Putting two files in the same module is also possible, for example to control the relative order of two lists with the nav key instead of rearranging text in one file.

Including a list from a partial

A navigation file may use include:: with the partial$ family. The included file is read as part of the navigation file, so it can hold a titled list, and tags and line ranges work as in any other include. The partial lives in the partials directory of a module, so it is not published as a page.

modules/ROOT/partials/extras-nav.adoc
.Extras
* xref:guides:converting-lengths.adoc[]
modules/ROOT/nav.adoc, last line
include::partial$extras-nav.adoc[]

Source: Antora docs: Include lists

The Extras list is appended after the lists above it. Because the partial uses an xref for a page of another module, the xref carries the guides module coordinate, as the paragraph on resolution below explains.

Nesting an included list

To make an included list the children of an item, attach the include to that item with a list continuation and wrap it in an open block. Antora fuses the included items into the parent and discards the block. The included file in this case is an anonymous list, without a title.

modules/ROOT/nav.adoc
* Downloads
+
--
include::partial$downloads-nav.adoc[]
--
modules/ROOT/partials/downloads-nav.adoc
* xref:attachment$units.csv[Unit table (CSV)]
* xref:attachment$pocket-units-sample.zip[Sample project]

Source: Antora docs: Include lists

How xrefs in included files resolve

An xref in a partial is resolved relative to the page or navigation file that includes it, not relative to the partial. Use a resource ID that is valid in every place the partial is included. For a navigation partial that is always included in a ROOT navigation file, that means module-qualified xrefs for pages of other modules.

A complete example

The Pocket Units component below combines everything: titled lists, a non-link group, a fragment, an external link, an included partial with attachments, and a second module. It was built with Antora 3.2.1 from a local Git repository and the Antora Default UI, and the build finished without warnings.

modules/ROOT/nav.adoc
.Pocket Units
* xref:index.adoc[]
* xref:getting-started.adoc[]
* Reference
** xref:api.adoc[]
** https://example.org/pocket-units/changelog[Online changelog]
** xref:getting-started.adoc#install[Install section]
* Downloads
+
--
include::partial$downloads-nav.adoc[]
--

include::partial$extras-nav.adoc[]

The Guides list comes from modules/guides/nav.adoc, shown earlier. The resulting menu, read from the generated HTML of getting-started.html, was:

Pocket Units
  Overview
  Quick start
  Reference
    API Reference
    Online changelog
    Install section
  Downloads
    Unit table (CSV)
    Sample project
Extras
  Converting Lengths
Guides
  Converting Lengths
  Custom Units

The same page can therefore appear in several lists: Converting Lengths is listed twice. Antora does not complain. The two attachment entries pointed to _attachments/units.csv and _attachments/pocket-units-sample.zip inside the component version’s output folder.

The flow from files to menu is shown below.

flowchart LR D["antora.yml: nav list"] --> A["modules/ROOT/nav.adoc"] D --> B["modules/guides/nav.adoc"] P1["partials/downloads-nav.adoc"] -. include .-> A P2["partials/extras-nav.adoc"] -. include .-> A A --> M["Menu tree of the component version"] B --> M M --> H["Page menu in the UI"]

Ordering of components

The order inside a component version is the order described above. The order of components in the component list of the UI is a different matter: the UI model variable site.components is sorted alphabetically by component title (the title key of antora.yml, or the name when the title is missing), and versions of each component run from the greatest to the least. Antora does not impose this order on the UI. In the Default UI the list is produced by the nav-explore partial, which loops over site.components. To use another order, customise that partial and pass the list to a helper of your own that rearranges it, or write the component menu by hand, which also lets you leave components out. Customising a UI is covered in templates and the UI model.

Source: Antora docs: How component versions are sorted

This site does not rely on that list: the home page is a hand-written project picker, as described in the case study.

Pitfalls

  • An unregistered navigation file is silently ignored. If a menu is empty, check the nav key first.

  • Do not store a navigation file under pages: it would be published as an ordinary page.

  • A leading space or a missing dot in a list title makes it ordinary text instead of a title.

  • An xref with a fragment needs explicit text; with empty text the menu entry has no useful label.

  • An attachment entry with empty text shows the resource ID as its label.

  • Unqualified xrefs in a partial are resolved against the including file. A navigation partial that is included from another module must use qualified IDs.

  • A page can be part of the site without any navigation entry. It is then reachable only through links, search and the sitemap.

References