Navigation Link Syntax, Content, and Styles

List titles and items in a navigation file can contain several types of content, such as text, images, and icons. In most cases this content will link to a page or resource in your site.

When content is linked, then a website visitor can click on the visible content and jump to another page or resource. The syntax used to link the content depends on what the destination page or resource is and where it is located.

Site pages

When the link destination is a page in your site, the link is created using the Antora cross referencing system (xref:page-id.adoc[link content]).

Site attachments

When the link destination is an attachment in your site (i.e., stored in assets/attachments), such as a PDF or downloadable ZIP, the link is created using the link macro (link:{attachmentsdir}/filename.ext[link content]).

Other websites and resources

When the link destination is a website or resource that isn’t part of your site, i.e., it isn’t stored in a documentation component, the link is created using a valid URI scheme and address ([link content]).

Site page links

Cross references in a navigation list use the same syntax and page ID construction as cross references in the page content. Just set up the xref macro, insert the destination page ID, and add the link content. The link content can be text, images, and/or icons. The link content is visible to the visitor in the component navigation menu. It is also displayed in the breadcrumbs at the top of the destination page. When a visitor clicks on the link content, they are routed to the destination page specified by the page ID in the xref.

Whether in the body of a site page (i.e., AsciiDoc document stored in <module>/pages), or in a navigation file, always create page-to-page or navigation-to-page links using the page cross reference syntax. Antora’s page IDs are what allows your site to be portable across environments, domains, and versions.

The most common items in a navigation list are xrefs to pages in the same module where the navigation file is stored. In this case, the page ID doesn’t require the component or module coordinates.

xrefs to in-module pages
.xref:index.adoc[In-module page]
* xref:a-page-in-this-module.adoc[Another in-module page]
** xref:another-page.adoc#and-fragment[An in-module page deep link]
* xref:topic/page.adoc[In-module page in a topic folder]

Using the appropriate page ID pattern, you can link to any document in the site from a navigation list, whether it’s stored in a different module or component.

xrefs to pages in other modules and components
* xref:index.adoc[In-module page]
* xref:other-module:page.adoc[Page in the same component, but a different module]
** xref:topic/page.adoc[In-module page in a topic folder]
*** xref:other-module:page.adoc#fragment[A deep link to a page in the same component, but a different module]
*** xref:other-component:module:page.adoc[Page in another component]

Site resource links

An attachment is a resource stored in a module’s attachments directory (assets/attachments), such as a PDF or a sample project ZIP archive, that you want your user to visit or download. To insert a link to an attachment, use the AsciiDoc link macro (link:[]).

Attachment link syntax
* link:{attachmentsdir}/filename.ext[Link to resource in attachments directory]

Other website and resource links

A navigation list can contain links to websites and resources that are not part of your site. These links are created using the AsciiDoc URI syntax, which requires a valid URI scheme and address.

Link to an external website
*[Link to another website]

Unlinked content

When you want to include content in a navigation list, but you don’t want it to be a link, simply don’t mark it up with any link syntax.

* Unlinked Content
** xref:a-page.adoc[Linked Content]

Formatted text

Whether linked or unlinked, the text you want displayed in your component menu can be formatted using inline AsciiDoc markup.

* xref:index.adoc[*Bold linked text*]
* `Monospaced` text
*[Some __ita__lic letters]


A navigation item can be an image. To include an image, use the inline image macro (image:filename.ext[]). The inline image macro has only one colon (:).

.image:status.png[] (1)
* xref:index.adoc[image:star.svg[] What's New] (2)
1 Unlinked image
2 Linked image

What’s next?

Learn how to register navigation files so they get included in a component menu:

Learn all about structuring navigation lists: