Resource ID Coordinates

Coordinate syntax and order

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.

Diagram of a fully qualified Antora resource ID
Figure 1. 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 component version and module of the current page in relation to the target resource,

  • the family of the target resource, and

  • the AsciiDoc syntax used to reference the target resource.

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.

Example of an xref in the current page referencing a target resource
Figure 2. The current page, with the filename satellites.adoc, containing an xref macro referencing a 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.

Version 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.

Component coordinate

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.

Module coordinate

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.

Family coordinate

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:

  • the family of the target resource, and

  • the AsciiDoc syntax used to reference the target resource.

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.

Resource being referenced Syntax referencing the resource Family coordinate required?

Attachment

Xref macro

Yes, the attachment$ coordinate is required. See Attachments.

Example

Include directive

Yes, the example$ coordinate is required. See Include an Example.

Image

Block image macro

No, the family coordinate isn’t required. See Add Block Images and Image Resource ID Examples.

Inline image macro

No, the family coordinate isn’t required. See Add Inline Images and Image Resource ID Examples.

Xref macro

Yes, the image$ coordinate is required.

Page

Xref macro

No, the family coordinate isn’t required. See Xref Macros and Page Links.

Include directive

No, the family coordinate isn’t required. See Include a Page.

Partial

Include directive

Yes, the partial$ coordinate is required. See Include a Partial.

File coordinate

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 target resource doesn’t have a file extension, such as Dockerfile, and

  • the target resource is a partial or example.

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.

Example 1. Resource stored at root of family directory
📂 modules
  📂 admin
    📂 pages (1)
      📄 modes.adoc (2)
1 pages family directory
2 Page stored at the root of the pages directory

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.

Example 2. Resource stored in subdirectory of family directory
📂 modules
  📂 admin
    📂 pages
      📄 modes.adoc (1)
      📂 fields (2)
        📂 level (3)
          📄 routes.adoc (4)
          📄 terrain.adoc (5)
1 Page stored at the root of the pages directory
2 Subdirectory in the pages directory
3 Subdirectory in the fields subdirectory
4 Page stored in level subdirectory
5 Page stored in level subdirectory

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.

Example 3. Resources stored in the same subdirectory
📂 modules
  📂 admin
    📂 pages
      📂 fields
        📂 level
          📄 routes.adoc (1)
          📄 terrain.adoc (2)
1 Page stored in level subdirectory
2 Page stored in level subdirectory

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.