Metanorma: Aequitate Verum




Images are inserted into a Metanorma AsciiDoc document through the image command.

There are two types of AsciiDoc images:

  • block image;

  • inline image.

Metanorma AsciiDoc supports most of the features of image defined in Asciidoctor AsciiDoc.

Please refer to figures for details on how to use images within figures.

This page mainly describe Metanorma AsciiDoc behavior. For typical image command attributes, refer to Asciidoctor AsciiDoc.

Block image


A block image is displayed as a discrete element, i.e., on its own line, in a document.

The syntax used to enter a block image is as follows.

The image:: line is preceded by a blank line, entered on a line by itself, and then followed by a blank line.


Where PATH is the image path.

In Metanorma, block images are always entered as a figure. Please refer to the documentation on Figures.

Example 1. Including a block image
[[my-anchor]] (1)
.Title for image (2)
image::images/path.png[Alt text] (3)
  1. Optional anchor for referencing

  2. Image title

  3. Image command with path and optional alt text. If no alt text is provided, leave the square brackets at the end empty (image::path[]).


Inline image

An inline image is displayed in the flow of another element, such as a paragraph.

This is useful when you want to incorporate buttons or other icons inside the text flow.

Inline images are inserted using the inline image command: image:[] (instead of image::[]).

Example 2. Including an inline image into text flow
This is an inline image:{PATH}[], appearing within a paragraph.

Where PATH is the image path.

Data URIs

Metanorma allows Data URIs as the address for an image:

Example 3. Including an image via Data URI
image::data:image/png;base64,ivBO...[alt text]
Data URIs are only supported by Metanorma AsciiDoc, not other AsciiDoc processors.

Image directory root path

The root path for all image paths can be defined at the document-level, through the document attribute :imagesdir:.

Example 4. Setting an image directory root path
= Document title
:imagesdir: my-images (1)

image::myimage01.png[] (2)
  1. The document attribute :imagesdir: will set all root paths of the image command to the specified path.

  2. The reference to myimage01.png is joined with the path set at :imagesdir:, which results to my-images/myimage01.png.

More details of the :imagesdir: attribute can be found at documentation of Asciidoctor AsciiDoc.


Image size


Size of an image can be modified via the height and width attributes.


Height of image. Valid values listed below.


(default) Image will be shown according to the best visual settings determined by Metanorma


Fixed height in pixels (px). The px suffix can be omitted.


Width of image. Valid values listed below.


(default) Image will be shown according to the best visual settings determined by Metanorma


Fixed width in pixels (px). The px suffix can be omitted.


PDF-specific. Specifies that the image spans the whole page width regardless of the number of columns on the page. [added in]

This feature is not supported in typical AsciiDoc.

PDF-specific. Specified that the image will be as wide as the text column that contains it. [added in]

This feature is not supported in typical AsciiDoc.
The pixel is the only currently supported unit in image sizing.
Fixed dimensions
Example 5. Image resizing specifying height and width attributes in pixels

In the height and width attributes, the px suffix may be omitted.

Example 6. Image resizing with values omitting px unit in height and width
Scaling according to aspect ratio

The auto value indicates that the dimension does not have a fixed size but retain the aspect ratio of the original image.

Example 7. Aspect ratio is retained with width set to auto based on the value of height

An unspecified dimension is considered auto.

Example 8. Aspect ratio is retained when setting height but not width
PDF-specific width values

In the PDF paged layout, the width attribute can take on additional values.

The values full-page-width and text-width are used in PDF to indicate how wide an image is rendered against text, particularly if the text is formatted in multiple columns [added in].

Example 9. Setting width=full-page-width for an image in PDF
Example 10. Setting width=full-page-width for a figure in PDF
Treatment of image resizing may slightly differ across output formats.

Other attributes

For general attributes of the image command, please refer to the Asciidoctor AsciiDoc documentation.