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.
Link types
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 (
https://website.com[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.
In-module page links
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.
.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]Links to pages in other modules and components
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.
* 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:[]).
* 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.
* https://other-website.com/url[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
* https://other-website.com[Some __ita__lic letters]Images
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 |