Image Resource ID Examples
You can embed an image into any page in your site, regardless of the module, component, or version the target image file belongs to. Remember, don’t include the family coordinate in an image’s resource ID. It’s applied automatically at runtime when a resource ID is entered into an AsciiDoc image macro.
| If you’re looking for examples where the image and page belong to the same module and component version, see the Inline images or Block images pages. |
Use an image from another module
The target resource’s module coordinate and resource coordinate are required when the current page and target resource file belong to different modules of the same component version.
image::module:target-resource-filename.ext[optional attributes]
To use an image that belongs to another module, specify the image’s module name, followed by a colon (:).
Then enter the image’s filename, including its extension, followed by a set of square brackets ([]).
For context, let’s use the pages and images that belong to the component version colorado 5.2 as the basis for the examples in this section.
The component version’s source files are stored in the set of standard directories listed in Example 2.
📒 repository
📄 antora.yml
📂 modules
📂 la-garita
📂 images
📄 wilderness-map.jpg
📂 pages
📄 cochetopa-pass.adoc
📄 index.adoc
📂 ROOT
📂 images
📄 peak.svg
📂 pages
📄 index.adoc
📄 ranges.adoc
In Example 3, the image peak.svg belongs to the ROOT module.
It’s used in the page cochetopa-pass.adoc.
The elevation is image:ROOT:peak.svg[] 10,067 ft (3,068 m).
In Example 4, the wilderness-map.jpg image belongs to the la-garita module and is referenced by a page in the ROOT module.
image::la-garita:wilderness-map.jpg[]
Use an image from another docs component
When the current page and the target resource belong to different docs components, you must, at a minimum, specify the target component, module, and resource coordinates. You’ll almost always want to specify the target version coordinate, too.
image::version@component:module:target-resource-filename.ext[]
For context, let’s use the pages and images that belong to the component versions colorado 5.2 and wyoming 1.0 as the basis for the examples in this section.
Their source files are stored in the standard directory trees listed in Example 5.
📒 repository
📄 antora.yml (1)
📂 modules
📂 la-garita
📂 pages
📄 cochetopa-pass.adoc
📄 index.adoc
📂 ROOT
📂 images
📄 peak.svg
📂 pages
📄 index.adoc
📄 ranges.adoc
📒 repository
📂 docs
📄 antora.yml (2)
📂 modules
📂 sierra-madre
📂 images
📄 panorama.png
📂 pages
📄 wilderness-areas.adoc
| 1 | Declares files that belong to the colorado 5.2 component version |
| 2 | Declares files that belong to the wyoming 1.0 component version |
Example 6 shows an inline image macro.
The image macro will embed the image peak.svg (target resource), which belongs to the component version colorado 5.2, into the current page.
The current page, wilderness-areas.adoc, belongs to the component version wyoming 1.0.
image:5.2@colorado::peak.svg[] Bridger Peak is in the Sierra Madre range.
Notice in Example 6 that the module name ROOT seems to be missing from the resource ID.
When a component coordinate is specified in a resource ID, and the target resource belongs to the ROOT module, the module coordinate ROOT doesn’t have to be explicitly specified.
But you must still enter the colon : that would follow the module coordinate.
You can see this : directly before the resource coordinate peak.svg.
This shorthand is only valid when a component coordinate is specified and the target module is ROOT.
In all other cases where the module coordinate is required, the name of the module must be specified.
Let’s reference the image panorama.png (target resource) from ranges.adoc (current page) in Example 7.
panorama.png belongs to the the sierra-madre module of the wyoming component.
image::1.0@wyoming:sierra-madre:panorama.png[]
You probably noticed that the version coordinate is specified in both Example 6 and Example 7. You’ll usually want to identify a version when referencing an image that belongs to a different docs component than the current page. If you don’t specify the version, Antora will use the image file from the most recent version of the target component at runtime.
Use the latest version of an image
| This behavior only applies when the target resource file and current page belong to different docs components! |
If a version isn’t specified in the target resource ID, and the target resource and current pages belong to a different docs components, Antora will use the latest version of the target component to complete the resource ID.
Using the component versions previously described in Example 5, let’s create an image macro in the page index.adoc (current page) that uses the panorama.png image (target resource).
The image macro is shown below in Example 8.
index.adoc belongs to version 5.2 of the component colorado.
panorama.png belongs to version 1.0 of the component wyoming.
Notice that the target resource’s version coordinate isn’t specified.
image::wyoming:sierra-madre:panorama.png[]
Since there isn’t a version coordinate in Example 8, Antora will automatically complete this resource ID at runtime using the latest version — 1.0 — of the wyoming component.
If you were to release a more recent version of wyoming, such as version 1.5, and add it to your site, the image macro in Example 8 will automatically use the panorama.png image in version 1.5 of wyoming.
| This behavior of linking to the latest version only applies when the version coordinate is unspecified and the target resource and current page belong to different docs components. If you don’t specify a version and a component in the resource ID, Antora assumes the target resource’s version and component are the same as the current page’s version and component coordinates. |
Use an image from another version
When the current page and target resource belong to the same component, but the target resource belongs to a different version of that component, you’ll specify the target version, module (if it’s different), and resource coordinates.
image::version@module:target-resource-filename.ext[]
If the target resource and current page belong to the same module, too, then you only need to specify the target version and resource coordinates.
image::version@target-resource-filename.ext[]
For context, let’s use the images and pages that belong to the component versions colorado 5.2 and colorado 5.0 as the basis for the example in this section.
Their source files are stored in the standard directory trees listed in Example 11.
📒 repository | branch name v5.2.x
📄 antora.yml <- Declares files belong to colorado 5.2
📂 modules
📂 la-garita
📂 images
📄 wilderness-map.jpg
📂 pages
📄 cochetopa-pass.adoc
📂 ROOT
📂 pages
📄 index.adoc
📄 ranges.adoc
📒 repository | branch name v5.0.x
📄 antora.yml <- Declares files belong to colorado 5.0
📂 modules
📂 la-garita
📂 pages
📄 cochetopa-pass.adoc
📂 ROOT
📂 pages
📄 index.adoc
📄 ranges.adoc
📄 views.adoc
Notice that the colorado 5.2 component version has an image wilderness-map.jpg that belongs to the la-garita module.
In colorado 5.0, no such image file exists, but we can still use the image that belongs to 5.2 in the version 5.0 pages.
In Example 12 the image wilderness-map.jpg (target resource) is embedded in the page views.adoc (current page) that belongs to the colorado 5.0 component version.
image::5.2@la-garita:wilderness-map.jpg[]