Resource ID Coordinates

A resource ID contains five coordinates: version, component, module, family, and file. Antora constructs a resource ID for a source file by assigning values to these coordinates based on the file, standard directory set, and information in the component version descriptor. You can reference a resource from any other resource—​regardless of the component version each resource belongs to—​using a sequence of the resource ID coordinates assigned to a resource.

Figure 1 shows the coordinate types and their sequence in a fully qualified resource ID.

A fully qualified resource ID is a resource ID with all of its coordinates specified. You probably won’t have to use a resource’s fully qualified resource ID that often. The number of resource ID coordinates you specify when referencing a resource depends on:

The target resource is the resource source file that’s referenced, by specifying its resource ID, in an AsciiDoc macro, include directive, or other syntax. The current page is the page file that contains the AsciiDoc syntax that references the target resource.

In Figure 2, satellites.adoc is the current page and the resource with the filename modes.adoc is the target resource being referenced by the xref macro. The following sections describe how to determine the value of each coordinate for a target resource and when to use each coordinate.

The version coordinate is the same value as the version of the component to which the target resource belongs. The value of the version is assigned to the version key. The version key is specified either in the antora.yml file that defines the resource’s component version or on the content source in your playbook that specified from where Antora collected the component version’s files.

The version coordinate should be used to reference a resource in a different version of the same component or a specific version of a different component. When entering a version coordinate in a resource ID, it should always be the first coordinate and end with an at sign (@). If the component coordinate is not specified, the current component will be used. If the component coordinate is specified without specifying a version coordinate, the latest version of that component will be choosen.

The component coordinate is the name of the component to which the target resource belongs. The component name is specified by the name key in the antora.yml file that defines the resource’s component version.

The component coordinate must be used when the target resource and current page belong to different documentation components. The component name is entered before the module coordinate in a resource ID and is directly followed by one colon (:). If the component coordinate is specified without specifying a version coordinate, the latest version of that component will be choosen.

The module coordinate is the name of the module to which the target resource belongs. The module name is derived from the module directory where the resource is stored.

The module coordinate must be used when the target resource and current page belong to different modules. The module name is entered before the family coordinate, if the family coordinate is present, or before the file coordinate if the family coordinate isn’t present. The module name is directly followed by one colon (:).

When a module coordinate ends with the name of a built-in AsciiDoc macro, such as link, kbd, menu, etc., you may have to escape that portion of the coordinate by prefixing the macro name with a backslash. For example, module coordinates such as monolink and redmenu may need to be entered as mono\link and red\menu in a resource ID.

The family coordinate identifies the name of the family to which the target resource belongs. The family is derived from the family directory where the resource is stored. Remove the “s” at the end of the family’s name and replace it with a dollar sign ($) when constructing a resource ID. The valid family coordinates are page$, image$, partial$, example$, and attachment$.

Whether the family coordinate needs to be entered in a resource ID depends on:

For example, if you reference a page using the xref macro, the page$ family coordinate isn’t required because the xref macro applies it by default when no family coordinate is specified. The following table lists when the family coordinate is required depending on the resource being referenced and the syntax that is referencing the resource.

The file coordinate specifies the path, relative to the family directory, of the target resource’s source file. The file coordinate must specify the resource’s file extension except when:

The file coordinate for a resource stored at the root of a family directory is the name of the resource’s source file and its file extension.

For example, the file coordinate for modes.adoc, shown in Example 1, is modes.adoc because it’s stored at the root of the pages family directory.

If the target resource is located in a subdirectory of a family directory, the file coordinate must specify the family-relative directory path to the target resource.

The page terrain.adoc, shown in Example 2, is stored in the level subdirectory. The file coordinate for terrain.adoc is fields/level/terrain.adoc. If modes.adoc (current page) references terrain.adoc (target resource), the file coordinate specified in the target resource’s resource ID is fields/level/terrain.adoc. If terrain.adoc (current page) references modes.adoc (target resource), the file coordinate specified in the target resource’s resource ID is modes.adoc. Remember, the file coordinate of the target resource is always calculated from the family directory.

When the target resource and current page are both located in the same subdirectory of a family directory, the relative path token, ./, can be used to abbreviate the family-relative directory path of the target resource’s file coordinate.

The pages routes.adoc and terrain.adoc, shown in Example 3, are both stored in the level subdirectory. If routes.adoc (current page) references terrain.adoc (target resource), the file coordinate specified in the target resource’s resource ID can be specified as ./terrain.adoc instead of fields/level/terrain.adoc.