Image Resource ID Examples

You can insert an image into any page in your site, regardless of the module or component version to which the target image file belongs. On this page, you’ll learn how to assign the correct resource ID coordinates to an image macro based on the version, component, and module the image belongs to in relation to the page where you want to embed it.

For an overview of the block image macro and inline image macro and step-by-step instructions on how to add them to a page, see:

If you aren’t familiar with the Antora resource ID or its coordinates, see:
All of the examples on this page, regardless of the image macro they use to demonstrate a concept, apply to both the block image macro and inline image macro.

Use an image within a module

Most of the images you reference with an image macro will probably belong to the same module and component version as the current page. In such circumstances, the AsciiDoc image macros only require the file coordinate of the target image’s resource ID be assigned as a value.

The target image is the image source file that’s being referenced by the current page. The target image is referenced by assigning its resource ID to an inline or block image macro in the content of the current page. The current page is the page source file containing the image macro that references the target image.

The structure of the target image’s file coordinate varies depending on whether the target image is stored at the root of the images family directory or in a subdirectory of the images directory.

Example 1. current-page.adoc
image:target-image-filename.ext[optional attribute] (1)

image:path/to/target-image-filename.ext[optional attribute] (2)

image:./target-image-filename.ext[optional attribute] (3)
1 File coordinate of the target image when it’s stored at the root of the images directory.
2 File coordinate of the target image when it’s stored in a subdirectory of the images directory.
3 File coordinate of the target image when the target image and current page are stored in a subdirectory with the same family-relative directory path. This is an advanced use case.

The following sections provide examples showing the different file coordinate structures.

File coordinate at images directory root

When the target image is stored at the root of the images family directory, the file coordinate is the target image’s filename and file extension. Remember, the file coordinate of the target image is always calculated from the root of the images family directory.

Example 2. File coordinate in an image macro when the target image is stored at the root of an images directory
image::target-image-filename.ext[optional attribute]

Let’s use the files that belong to the component version colorado 5.2 as the basis for the example in this section. The component version’s source files are assigned to modules and families based on the set of standard directories listed in Example 3.

Example 3. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita (2)
    📂 images (3)
      📄 wilderness-map.jpg
    📂 pages (4)
      📄 ridge.adoc
1 Defines the component version as colorado 5.2
2 Defines a module named la-garita
3 Defines subsequent files as images
4 Defines subsequent files as pages

Using the two files that belong to the la-garita module, shown in Example 3 above, let’s insert the wilderness-map.jpg image into the ridge.adoc page. That means the source file wilderness-map.jpg is the target image and ridge.adoc is the current page.

Example 4 shows a block image macro in the ridge.adoc page (current page) that references, the wilderness-map.jpg image (target image). When the target image and current page belong to the same module, only the file coordinate of the target image’s resource ID needs to be entered in the image macro.

Example 4. ridge.adoc (current page)
The trailhead is north of town.

image::wilderness-map.jpg[]

In Example 4, the file coordinate for the wilderness-map.jpg image is wilderness-map.jpg. Its file coordinate consists solely of its filename and file extension because wilderness-map.jpg is stored at the root of the images directory.

If the target image is stored in a subdirectory of the images directory, its file coordinate must specify the images-relative directory path, filename, and file extension. See File coordinate with images-relative directory path for file coordinate examples when the target image is stored in a subdirectory.

File coordinate with images-relative directory path

The images-relative directory path of the target image is required in its file coordinate when it’s stored in a subdirectory of the images directory.

Example 5. File coordinate in an image macro when the target image is stored in a subdirectory of an images directory
image::path/to/target-image-filename.ext[optional attribute]

Let’s use the pages that belong to the component version shown in Example 6 as the basis for the examples in this section.

Example 6. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita (2)
    📂 images (3)
      📂 aerial (4)
        📄 skyline.jpg
    📂 pages (5)
      📄 ridge.adoc
1 Defines the component version as colorado 5.2
2 Defines a module named la-garita
3 Defines subsequent files as images
4 A subdirectory in images containing the source files of images
5 Defines subsequent files as pages

Let’s reference skyline.jpg from ridge.adoc. As you can see in Example 6 above, the image and page belong to the la-garita module. In Example 7, an image macro in the ridge.adoc page (current page) references the skyline.jpg image (target image).

Example 7. ridge.adoc (current page)
= La Garita Ridgeline

image::aerial/skyline.jpg[]

As shown in Example 7, the file coordinate for skyline.jpg is aerial/skyline.jpg. The file coordinate for skyline.jpg consists of its images-relative directory path, filename, and file extension because it’s stored in the subdirectory aerial.

In special circumstances where the images-relative directory path of the target image and the pages-relative directory path of the current page are parallel, the images-relative directory path of the file coordinate can be replaced with the relative path token, ./.

Use an image from another module

When the target image and current page don’t belong to the same module, you must specify the target image’s module coordinate and file coordinate in the image macro.

Example 8. Module and file coordinates assigned to an image macro
image:module:target-image-filename.ext[optional attribute] (1)

image:module:path/to/target-image-filename.ext[optional attribute] (2)
1 The image macro is assigned the module coordinate and file coordinate of the target image when the target image doesn’t belong to the same module as the current page. The target image’s file coordinate is its filename and file extension when the target image is stored at the root of an images family directory.
2 If the target image is stored in a subdirectory of an images directory, the target image’s file coordinate must specify its images-relative directory path, filename, and file extension.

Let’s use the files that belong to the component version shown in Example 9 as the basis for the examples in this section.

Example 9. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita (2)
    📂 images (3)
      📂 aerial (4)
        📄 skyline.jpg
    📂 pages (5)
      📄 ridge.adoc
      📄 willow-creek.adoc
  📂 ROOT (6)
    📂 images (7)
      📄 peak.svg
    📂 pages (8)
      📄 index.adoc
      📄 ranges.adoc
1 Defines the component version as colorado 5.2
2 Defines a module named la-garita
3 Defines subsequent files as images
4 A subdirectory in images containing the source files of images
5 Defines subsequent files as pages
6 Defines the ROOT module
7 Defines subsequent files as images
8 Defines subsequent files as pages

From the colorado 5.2 component version, shown in Example 9 above, let’s insert the peak.svg image into the willow-creek.adoc page. That means the source file peak.svg is the target image and willow-creek.adoc is the current page.

Example 10 shows an inline image macro in willow-creek.adoc (current page) that references the image file peak.svg (target image). The module and file coordinates of the target image’s resource ID are assigned to the image macro. The willow-creek.adoc page belongs to the la-garita module. The peak.svg image belongs to the ROOT module.

Example 10. Insert peak.svg (target image) into willow-creek.adoc (current page)
The elevation is image:ROOT:peak.svg[] 10,067 ft (3,068 m).

As shown in Example 10, the target image’s module coordinate is ROOT and its file coordinate is peak.svg.

In Example 11, let’s embed the skyline.jpg image (target image) into ranges.adoc (current page). The skyline.jpg image belongs to the la-garita module and ranges.adoc belongs to the ROOT module.

Example 11. Insert skyline.jpg (target image) into ranges.adoc (current page)
image::la-garita:aerial/skyline.jpg[]

As shown in Example 11, the target image’s module coordinate is la-garita and its file coordinate is aerial/skyline.jpg because it’s stored in the aerial subdirectory of the images family directory.

Use an image from another docs component

When the target image and current page belong to different documentation components, you must specify, at a minimum, the target image’s component, module, and file coordinates in the image macro. You’ll almost always specify the version coordinate, too.

Example 12. Version, component, module, and file coordinates assigned to an image macro
image:version@component:module:target-image-filename.ext[optional attribute] (1)

image:version@component:module:path/to/target-image-filename.ext[optional attribute] (2)

image:component:module:file-coordinate-of-target-image.ext[optional attribute] (3)
1 The image macro is assigned the version, component, module, and file coordinates of the target image when the target image and current page don’t belong to the same component version. The target image’s file coordinate is its filename and file extension when the target image is stored at the root of an images family directory.
2 If the target image is stored in a subdirectory of an images directory, the target image’s file coordinate must specify its images-relative directory path, filename, and file extension.
3 If the version coordinate isn’t specified, Antora uses the latest version of the target image’s component to complete the resource ID at runtime. This behavior only applies when the target image and current page belong to different docs components.

Let’s use the files that belong to the component versions colorado 5.2 (Example 13) and wyoming 1.0 (Example 14) as the basis for the example in this section.

Example 13. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 images (3)
      📄 peak.svg
    📂 pages (4)
      📄 index.adoc
      📄 ranges.adoc
1 Defines the component version as colorado 5.2
2 Defines the ROOT module
3 Defines subsequent files as images
4 Defines subsequent source files as pages
Example 14. Directories and files assigned to wyoming 1.0
📄 antora.yml (1)
📂 modules
  📂 sierra-madre (2)
    📂 images (3)
      📄 panorama.png
    📂 pages (4)
      📄 elevation.adoc
      📄 wilderness-areas.adoc
1 Defines the component version as wyoming 1.0
2 Defines a module named sierra-madre
3 Defines subsequent files as images
4 Defines subsequent files as pages

Using files from Example 13 and Example 14, let’s insert panorama.png (target image) into ranges.adoc (current page). The image panorama.png belongs to the sierra-madre module of wyoming 1.0. In Example 15, the resource ID assigned to the image macro specifies the version, component, module, and file coordinates of the target image because the target image belongs to the wyoming 1.0 component version whereas the current page belongs to colorado 5.2.

Example 15. Insert panorama.png (target image) as a block image into ranges.adoc (current page)
image::1.0@wyoming:sierra-madre:panorama.png[]

As shown in Example 15, the target image’s version coordinate is 1.0, its component coordinate is wyoming, its module coordinate is sierra-madre, and its file coordinate is panorama.png.

Now, in Example 16, let’s insert peak.svg (target image) into wilderness-areas.adoc (current page). The peak.svg image belongs to the component version colorado 5.2. The wilderness-areas.adoc page belongs to the component version wyoming 1.0.

Example 16. wilderness-areas.adoc (current page)
image:5.2@colorado::peak.svg[] Bridger Peak is in the Sierra Madre range.

Notice in Example 16 that the module coordinate ROOT seems to be missing from the resource ID. When a component coordinate is specified in a resource ID, and the target image 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 file coordinate peak.svg. This shorthand only works when a component coordinate is specified and the module coordinate of the target image is ROOT. In all other cases where the module coordinate is required, the name of the module must be specified.

You may have noticed that the version coordinate is specified in both Example 15 and Example 16. If you don’t specify the version, Antora will complete the resource ID of the target image using the version coordinate of the target image’s latest component version at runtime.

Use the latest version of an image

This behavior only applies when the target image and current page belong to different docs components!

If a version isn’t specified in the resource ID, and the target image and current page belong to different documentation components, Antora uses the version coordinate of the latest version of the target image’s component to complete the resource ID at runtime.

Let’s use the files that belong to colorado 5.2 (Example 13 in the previous section), wyoming 1.0 (Example 14 in the previous section), and wyoming 1.5 (Example 17 below) as the basis for the example in this section.

Example 17. Directories and files assigned to wyoming 1.5
📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 images
      📄 panorama.png
    📂 pages
      📄 elevation.adoc
      📄 wilderness-areas.adoc
1 Defines the component version as wyoming 1.5

Let’s reference the panorama.png image (target image) from index.adoc (current page). index.adoc belongs to the colorado 5.2 component version . There are two files named panorama.png that belong to the wyoming component, sierra-madre module, and images family. One panorama.png belongs to version 1.0, the other panorama.png to version 1.5.

Example 18 shows a block image macro referencing panorama.png (target image) from index.adoc (current page). Notice that the target image’s version coordinate isn’t specified.

Example 18. index.adoc (current page)
image::wyoming:sierra-madre:panorama.png[]

When Antora runs, it will identify wyoming 1.5 as the latest version of the wyoming component according to its version sorting rules and latest version criteria. Because a version coordinate isn’t specified in Example 18, Antora will complete the resource ID assigned to the image macro using the version coordinate — 1.5 — of the latest wyoming component.

This behavior of linking to the latest version only applies when the version coordinate is unspecified and the target image and current page belong to different components. If the version and component coordinates aren’t specified in the resource ID, Antora assumes the target image belongs to the same component version as the current page and uses the current page’s version and component coordinates to complete the target image’s resource ID.

Use an image from another version of its component

When the current page and target image belong to the same component, but the target image belongs to a different version of the component, you’ll specify the version, module (if it’s different than the current page’s module), and file coordinates.

Example 19. current-page.adoc
image:version@module:file-coordinate-of-target-image.ext[optional attribute] (1)

image:version@file-coordinate-of-target-image.ext[optional attribute] (2)
1 The image macro is assigned the version, module, and file coordinates of the target image when the target image doesn’t belong to the same version and module as the current page.
2 The image macro is assigned the version and file coordinates of the target image when the target image doesn’t belong to the same version as the current page.

Let’s use the files that belong to the component version colorado 5.2 (Example 20) and the component version colorado 6.0 (Example 21) as the basis for the example in this section.

Example 20. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 images
      📄 wilderness-map.jpg
    📂 pages
      📄 index.adoc
      ...
1 Defines the component version as colorado 5.2
Example 21. Directories and files assigned to colorado 6.0
📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 pages
      📄 index.adoc
      📄 ridge.adoc
      📄 willow-creek.adoc
1 Defines the component version as colorado 6.0

Notice that the colorado 5.2 component version in Example 20 has the image wilderness-map.jpg. However, colorado 6.0, shown in Example 21, has no such image file.

Let’s reference the image wilderness-map.jpg (target image), which belongs to colorado 5.2, from the ridge.adoc page (current page) that belongs to the colorado 6.0 component version. Both resources belong to the la-garita module. In Example 22, the image wilderness-map.jpg (target image) is embedded in the page ridge.adoc (current page).

Example 22. ridge.adoc (current page) in colorado 6.0
image::5.2@wilderness-map.jpg[]

As shown in Example 22, the target image’s version coordinate is 5.2 and its file coordinate is wilderness-map.jpg.