Page Identifier

In order for a page to be linked to, i.e., referenced, that page must have a unique and stable identifier. This identifier is like your mobile phone number. When someone calls your mobile number, they know they’re calling you and that they’ll reach your phone no matter where your phone is located. So, when an identifier is “called”, the page that is connected to that identifier answers, no matter where it’s published.

We call a page’s “number” a page identifier, or page ID for short.

The page ID is unique and stable because it’s constructed from the properties of the source document.

A page ID is based on a documentation component’s standard project structure. Documentation components ensure that each page lives in a defined, describable location. From this structure, each location derives unique, reliable coordinates we can use to refer to it.

These source document coordinates are described below.

These coordinates are organize in a standard structure to create a unique, fully-qualified page ID.

For example, this is the fully-qualified page ID for the “How Antora Works” page, which is located in the ROOT module of the Antora docs component.

A page ID is used in an AsciiDoc cross reference, also called an xref, to link one documentation page to another documentation page.

Here’s how that looks in practice:

Specifying the version, component, and even module every time seems like overkill, right? Don’t worry, there’s a shorthand.

For instance, if you’re linking to a page in the same module as the page you’re linking from, all you need to do is specify the page coordinate. The next example shows a cross reference from the “How Antora Works” page (how-antora-works.adoc) to the “Run Antora” page (run-antora.adoc). Both of these pages live in the same component and module.

A whole range of examples, from linking between different components to linking to different versions of a page, are explained in page cross references.

We’ve avoided coupling to the published URL by using a source-to-source reference. Notice the page coordinate ends with .adoc, the file extension of an AsciiDoc source file. Regardless of whether you’re deploying your site locally, to a staging or production environment, or you change URL strategies, the page ID always remains the same. The cross reference locks on to the target page and produces a URL that points to it wherever it gets published.

We’ve avoided coupling to the filesystem by using a location based on the documentation component structure. The page ID describes the source file’s project (component & version) and where the source file is located in that project (module, family, & family-relative path).

We’ve eliminated the relative path (../../) problem by specifying the page as a module-relative path. The path always starts from a module’s pages directory, even when the referencing page is located inside a topic folder. If you move or rename a page within a module, you don’t have to change any references to other pages.

This human-friendly referencing system saves you from having to do computations in your head while writing. You just specify the coordinates of the page you want to reference. There’s no need to worry about the source file’s physical location on disk or its published URL. All you need to know are the names of your components, versions, modules, and pages so you can fill in this information.