Images

General

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.

image::{PATH}[]

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)

Optional anchor for referencing
Image title
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]

Note	Data URIs are only supported by Metanorma AsciiDoc, not other AsciiDoc processors.

By default, images are stored in Metanorma Semantic and Presentation XML as Data URI, rather than as links to external image files, so that Metanorma XML and HTML can be distributed as single files, without bundling image files separately.

This behaviour can be disabled by setting :data-uri-image: false [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0].

In order to prevent the Metanorma processor from running out of memory, a maximum permitted size for Data URI-encoded images is enforced.

By default, the maximum size is 13981013 bytes. This corresponds to the Base64 encoding of a 10 MB image.
The size can be changed by setting :data-uri-maxsize:.
If :data-uri-maxsize: is set to 0, no maximum size is enforced. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.1].

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)

The document attribute :imagesdir: will set all root paths of the image command to the specified path.
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.

Attributes

Image size

General

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

height

Height of image. Valid values listed below.

auto: (default) Image will be shown according to the best visual settings determined by Metanorma
{pixels}px: Fixed height in pixels (px). The px suffix can be omitted.

width

Width of image. Valid values listed below.

auto

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

{pixels}px

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

full-page-width

PDF-specific. Specifies that the image spans the whole page width regardless of the number of columns on the page. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.6]

Note	This feature is not supported in typical AsciiDoc.

text-width

PDF-specific. Specified that the image will be as wide as the text column that contains it. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.6]

Note	This feature is not supported in typical AsciiDoc.

Note	The pixel is the only currently supported unit in image sizing.

Fixed dimensions

Example 5. Image resizing specifying height and width attributes in pixels

image::logo.jpg[height=150px,width=100px]

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

image::logo.jpg[height=150,width=100]

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

image::logo.jpg[height=150,width=auto]

An unspecified dimension is considered auto.

Example 8. Aspect ratio is retained when setting height but not width

image::logo.jpg[height=150]

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 https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.6].

Example 9. Setting width=full-page-width for an image in PDF

[width=full-page-width]
image::abc.png[]

Example 10. Setting width=full-page-width for a figure in PDF

[.figure,width=full-page-width]
====
image::abc.png[]
====

Note	Treatment of image resizing may slightly differ across output formats.

Other attributes

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