Resources and Resource IDs
No matter which component version or module a resource’s source file belongs to, you can add it to any page in your site using its resource ID and the applicable AsciiDoc syntax.
What’s a resource ID?
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.
A resource is a source file that is assigned to the attachments, examples, images, pages, or partials family. When a resource is referenced, the target value in the corresponding AsciiDoc macro or include directive must be a valid Antora resource ID.
In Antora, a resource is referenced using an AsciiDoc include directive, link macro, or image macro and the resource ID of the target resource. (Except for attachments.) The target resource is the source file that will be embedded in current page when the site is published. The current page is the page, partial, or example containing the AsciiDoc macro or directive that references the target resource.
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 page, partial, or example 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.
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 instance, 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.
On the other hand, the AsciiDoc include directive can be used to reference partials, examples, and pages, so a family coordinate must be specified in the target resource ID. The syntax that requires an explicit family coordinate is listed in the table below.
| Resource | Referencing syntax | Resource ID requirements |
|---|---|---|
Attachments |
|
Currently, an attachment can’t be referenced using a resource ID.
The attribute reference |
|
The |
|
|
No family coordinate required; it’s automatically applied at runtime. See Add block images and Image resource ID examples. |
|
|
No family coordinate required; it’s automatically applied at runtime. See Add inline images and Image resource ID examples. |
|
|
The |
|
|
The |