Insert an Image

On this page, you’ll learn:

The basic structure of the block image macro.
The basic structure of the inline image macro.
How to insert an image into a page using its resource ID.

Block and inline images

There are two image macro types, block and inline.

This is a paragraph.

image::resource-id[optional attributes] (1)

This is a sentence with an inline image image:resource-id[optional attributes]. (2)

1	A block image is designated by two colons (`::`) after the macro name. It’s preceded by a blank line, entered on a line by itself, and then followed by blank line.
2	An inline image is entered into the flow of the content. It’s designated by a single colon (`:`) after the macro name.

Block image macro structure

A block image is usually displayed as a discrete element on a site page. Let’s break down the AsciiDoc syntax and resource coordinates you need to insert a block image into a page.

On 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.
```
This is a paragraph.

image::
```
Enter the resource ID of the image file. An image’s resource coordinates are assembled like the coordinates in an xref. In this example, the image file is stored in the same module as the page it is being inserted into, so you only need to identify the image’s file name. Enter the image’s file name, including its extension, directly after the colons.
```
image::name-of-file.ext
```
Complete the macro with a set of square brackets ([]).
```
image::name-of-file.ext[]
```
Press Enter twice after the last square bracket (]) to insert a new line after the image macro.
```
This is a paragraph.

image::name-of-file.ext[]

This is another paragraph.
```

Inline image macro structure

An inline image is displayed in the content flow of another element, such as a paragraph. The inline image macro is structured almost identically to the block image macro except for a few differences.

After the word or other content where you want to insert the image, press the SPACE bar once, and then enter the macro’s name followed by one colon (image:).
```
This sentence has an inline image:
```
Enter the resource ID of the image file. An image’s resource coordinates are assembled like the coordinates in an xref. In this example, the image file is stored in the same module as the page it is being inserted into, so you only need to identify the image’s file name. Enter the image’s file name, including its extension, directly after the colon. Then complete the macro with a set of square brackets ([]).
```
This sentence has an inline image:name-of-file.ext[]
```
Press the SPACE bar once after the last square bracket (]) to insert a space after the macro, then continue entering your content.
```
This sentence has an inline image:name-of-file.ext[] image in it.
Yet another sentence!
```

Use images stored in the same component but different modules

To use an image from the same component but a different module, the image’s resource ID needs to specify the module name where the image is stored. After the macro prefix, enter the name of the module where the image is stored followed by a colon (:). Then enter the image’s file name, including its extension, followed by a set of square brackets ([]).

image::name-of-module:name-of-file.ext[]

Example 1 and Example 2 are based on a component named colorado. Colorado contains two modules named la-garita and ROOT.

Directories and files in the Colorado component

colorado
  modules
    la-garita
      images
        wilderness-map.jpg
      pages
        cochetopa-pass.adoc
        index.adoc
    ROOT
      images
        peak.svg
      pages
        index.adoc
        ranges.adoc

In Example 1, the image peak.svg, stored in ROOT, is used in a page stored in the la-garita module.

Example 1. Insert peak.svg into cochetopa-pass.adoc

The elevation of Cochetopa pass is image:ROOT:peak.svg[] 10,067 ft (3,068 m).

In Example 2, the wilderness-map.jpg image, stored in la-garita, is referenced by a page stored in the ROOT module.

Example 2. Insert wilderness-map.jpg into ranges.adoc

image::la-garita:wilderness-map.jpg[]

Use images stored in different components

To use an image stored in another component, the image’s resource ID needs to specify the component and module where the image file is stored. After the macro prefix, enter the name of the component followed by a colon (:) and the name of the module followed by a colon where the image is stored. Then, enter the image’s file name, including its extension, followed by a set of square brackets ([]).

image::name-of-component:name-of-module:name-of-file.ext[]

When the image is stored in the ROOT module of another component, ROOT doesn’t need to be entered into the resource ID. It’s designated by entering another colon (:) directly after the colon following the component’s name.

image::name-of-component::name-of-file.ext[]

Example 3 and Example 4 are based on a component named colorado and a component named wyoming.

Directories and files in the Colorado component and Wyoming component

colorado
  modules
    ROOT
      images
        peak.svg
      pages
        index.adoc
        ranges.adoc
  ...

wyoming
  modules
    sierra-madre
      images
        elevation.png
      pages
        wilderness-areas.adoc
  ...

In Example 3, the image peak.svg, located in the ROOT module of the colorado component, is referenced by a page stored in the wyoming component.

Example 3. Insert peak.svg into wilderness-areas.adoc

image:colorado::peak.svg[] Bridger Peak is located in the Sierra Madre range.

In Example 4, the image elevation.png, located in the sierra-madre module of the wyoming component, is used in a page stored in the colorado component.

Example 4. Insert elevation.png into ranges.adoc

image::2.8@wyoming:sierra-madre:elevation.png[]

Specifically, we’re using the elevation.png file from version 2.8 of the Wyoming component. When referencing an image from another component, you’ll usually want to identify a specific version. Otherwise, when Antora builds your documentation site, it will use the image file from the most recent version of the component. The next section shows more examples of using the version coordinate.

Insert an image into a page from a different version

To use an image from a different version of a module or component, the image’s resource ID needs to specify the version and be followed by the appropriate module or component names if they’re needed.

After the block image macro prefix, enter the version name followed by the @ symbol. If the image is stored in the same module as the page you’re inserting it into (just in a different version of that module), you only need to specify the image’s file name after name-of-version@. Complete the macro with a set of square brackets ([]).

image::name-of-version@name-of-file.ext[]

If the image is stored in a different version and module of the same component, enter the module’s name after the @ symbol.

image::name-of-version@name-of-module:name-of-file.ext[]

image::name-of-version@ROOT:name-of-file.ext[]

When preceded by a component name, the ROOT module’s name doesn’t need to be entered. It’s designated by entering another colon (:) directly after the colon following the component’s name.

image::name-of-version@name-of-component::name-of-file.ext[]

image::name-of-version@name-of-component:name-of-module:name-of-file.ext[]