Resources and Resource IDs

No matter which component version or module a resource belongs to, it can be referenced by the other resources in your site using its resource ID and the applicable AsciiDoc syntax.

What’s a resource ID?

A resource is a source file that is assigned to the attachments, examples, images, pages, or partials family.

An Antora resource ID is a unique and reliable set of identifying coordinates, organized in a standard sequence, that are constructed from the properties assigned to each resource’s source file. In Antora, a resource is referenced using its resource ID.

What are the resource ID coordinates?

Antora constructs a resource ID for a source file from the key-value pairs specified in a component version descriptor and the standard directory set. Using this information, a resource can be referenced from any other resource in your site using a unique and reliable set of resource ID coordinates.

A fully qualified resource ID with its coordinates organized in the standard sequence is shown below.

version@component:module:family$resource.ext
version@

The first coordinate identifies the version of the component to which the target resource belongs. The version is specified by the version key in the antora.yml file that defines the resource’s component version. The version coordinate is directly followed by an at sign (@).

component:

The second coordinate identifies 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 name is directly followed by one colon (:).

module:

The third coordinate identifies 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 name is directly followed by one colon (:).

family$

The fourth 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. Whether or not the family coordinate needs to be specified depends on the AsciiDoc syntax used to reference the resource.

resource.ext

The fifth coordinate specifies the path, relative to the family directory, of the target resource’s source file. The filename must include the file extension.

How many resource ID coordinates you need to specify when referencing a resource depends on the component version and module of the current page in relation to the target resource.

The target resource is the source file that will be linked to from the current page or embedded in the current page when the site is published. The current page is the page file that contains the AsciiDoc macro or include directive that references the target resource.

When is the family coordinate required?

The family coordinate doesn’t always need to be specified in a resource ID. It may be implicitly assigned by the AsciiDoc syntax you use to reference the resource. For example, an image is always embedded in a page using an AsciiDoc image macro. Since images are only referenced using the image macros, the image$ coordinate is automatically applied to the target resource ID at runtime.

Resource Referencing syntax Example Resource ID requirements

Attachment

Xref macro

xref:attachment$brochure.pdf[]

The attachment$ coordinate is required. See Attachments.

Example

Include directive

include::example$app.rb[]

The example$ coordinate is required. See Include an Example.

Image

Block image macro

image::my-image.svg[]

No family coordinate required. See Add Block Images and Image Resource ID Examples.

Inline image macro

image:my-image.svg[]

No family coordinate required. See Add Inline Images and Image Resource ID Examples.

Page

Xref macro

xref:the-steps.adoc[]

No family coordinate required.

Include directive

include::the-steps.adoc[tag=overview]

No family coordinate required. See Include a Page.

Partial

Include directive

include::partial$my-partial.adoc[]

The partial$ coordinate is required. See Include a Partial.