Metanorma: Aequitate Verum

Author's documentation

Images

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

tag::tutorial[]

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)

  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[]).

end::tutorial[]

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.

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.

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.