Create a Navigation File
On this page, you’ll learn:
How to structure a navigation file.
How to add cross references to a navigation list.
How to add regular text and links to other websites to a navigation list.
Each module contains a navigation file named nav.adoc. In Antora, this navigation file is called linked navigation.
A navigation file is an AsciiDoc file (
.adoc) that contains one or more unordered lists.
In an AsciiDoc unordered list, each top-level navigation item is marked by a single (
Each top-level item can have as many nested items as you need up to level five (
Also, a list can have an optional title, denoted by a period (
.List title (optional) * First level (top) item ** Second level item *** Third level item **** Fourth level item ***** Fifth level item * First level item * First level item
A navigation file can contain multiple lists when each of those lists have a title. Each list must be separate by at least one blank line.
.List title * First level item ** Second level item * First level item ** Second level item .List title * First level item * First level item
The most common items in a navigation file are cross references to pages in the module where the navigation file will be stored.
.xref:index.adoc[Product Intro] * xref:get-started.adoc[Getting Started with Product] ** xref:install/prerequisites.adoc[Install the Prerequisites] * xref:page-a.adoc[Another Important Topic]
However, using the appropriate xref pattern, you can include references to any document in the site, whether it’s stored in the same module or not.
.xref:index.adoc[In-module page] * xref:other-module:page.adoc[Page in same component, but a different module] ** xref:topic/page.adoc[In-module page in a topic folder] * xref:component:module:page-a.adoc[Page in another component]
A navigation list can contain normal (i.e. unlinked) text.
.The Special Project (1) * xref:index.adoc[Project Intro] ** xref:get-started.adoc[Getting Started with Project] * Orientation (2) * xref:page-a.adoc[Project Concepts]
|1||An unlinked list block title|
|2||An unlinked list item|
A navigation list can contain links to external websites. External links are links to webpages that aren’t built as part of your documentation by your site’s Antora pipeline.
To create a list item that links to an external URL, just use AsciiDoc’s URL syntax.
.xref:index.adoc[The Special Project] * xref:get-started.adoc[Getting Started with Project] **xref:page-a.adoc[Project Concepts] * More Resources ** https://special-project.com/support[Support Plans] ** https://gitlab.com/project/issues