Add Block Images

On this page, you’ll learn:

The structure of the AsciiDoc block image macro.
How to insert a block image using its resource ID.

AsciiDoc block image macro

An AsciiDoc block image macro is used to embed the source file of an image into a partial or page. The block image macro accepts the Antora resource ID of PNG, JPG, SVG, and GIF (static and animated) image files as a value.

When Antora runs, the image file referenced by the block image macro is embedded and displayed as a discrete element in the published page. For example, the SVG image below this paragraph is embedded in this page using the block image macro.

Block image macro structure

Example 1 shows the structure of a block image macro.

Example 1. Block image macro

This is a paragraph.

image::resource-id-of-target-image.ext[optional attribute,optional attribute] (1)

This is another paragraph.

1	A block image is designated by two colons (`::`) after the macro name. It’s preceded by an empty line, entered on a line by itself, and then followed by an empty line.

At a minimum, a block image macro consists of the macro’s prefix (image::), the resource ID of the target image, and a set of square brackets ([]). 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.

Each part of the block image macro shown in Example 1 is described in more detail below.

image::: An block image macro begins with the macro’s name, image, followed by two colons (::).
resource ID of target image: The image macro accepts the resource ID of an image source file as its value. The value is entered directly after the second colon that follows the macro’s name (image::). How many of the target image’s resource ID coordinates you need to specify depends on the component version and module of the target image in relation to the current page. When referencing an image from an image macro, you don’t need to include the image$ family coordinate in the target image’s resource ID. It’s applied automatically at runtime.

[optional attribute,optional attribute]: The block image macro is completed with a set of square brackets ([]) at the end of the target image’s resource ID. You can leave the brackets empty, or assign one or more optional attributes as a comma-separated list inside the square brackets.

The next section, Embed a block image, explains how to set up an block image macro step-by-step.

Embed a block image

Let’s break down the block image macro and resource ID coordinates you need to insert an image (the target image) into a page (the current page) using the block image macro.

In your IDE or text editor, open the page where you want to insert an image. For this exercise, we’ve opened the file satellites.adoc. satellites.adoc is the current page.
In satellites.adoc, let’s embed the block image console.svg.
At the beginning of a new line, enter the macro’s name followed by two colons, image::. Make sure there is a blank line between the previous element, such as a paragraph or source block, and the line where you place the image macro.
Example 2. satellites.adoc (current page)
```
After scanning your badge, you should see this screen.

image::
```
Enter the resource ID of the target image file directly after the two colons. In this example, both console.svg and satellites.adoc belong to the same component version and module and the target image is stored at the root of the images family directory. Therefore, only the filename and extension of console.svg needs to be assigned as the value of the block image macro.
Example 3. satellites.adoc (current page)
After scanning your badge, you should see this screen. image::console.svg
Notice that the resource ID for console.svg doesn’t include its family coordinate. Antora automatically applies the image$ family coordinate to a resource ID assigned to an image macro.
Directly after the resource ID of the target image, enter an opening square bracket ([) and then a closing square bracket (]).
Example 4. satellites.adoc (current page)
After scanning your badge, you should see this screen. image::console.svg[]
We didn’t apply any optional attributes to the block image macro in this example; however, you can specify one or more attributes as a comma-separated list inside the square brackets.
Press Enter twice after the last square bracket (]) to insert a new line after the image macro.
Example 5. satellites.adoc (current page)
```
After scanning your badge, you should see this screen.

image::console.svg[]

Enter the satellite position after the prompt.
```

That’s it! You’ve finished inserting the target image (console.svg) into the current page (satellites.adoc) using the AsciiDoc block image macro.

Learn more

To learn how to embed images that belong to other modules, docs components, and versions, see Image resource ID examples.