Images

There are two directives to include images: image and figure.

Attention!

Images are not supported by the manpage writer.

It is up to the author to ensure compatibility of the image data format with the output format or user agent (LaTeX engine, HTML browser). The following, non exhaustive table provides an overview.

The html5 writer uses the <video> tag if the image URI ends with an extension matching one of the listed video formats (since Docutils 0.17). [2]

The html4 writer uses an <object> tag for SVG images and videos for compatibility with older browsers and for XHTML1.1 conformance respectively. [3]

When compiling with pdflatex, xelatex, or lualatex. The original latex engine supports only the EPS image format. Some build systems, e.g. rubber support additional formats via on-the-fly image conversion. Image

Directive Type:

"image"

Doctree Elements:

<image>, <reference> (only with option "target")

Directive Arguments:

one, required (image URI)

Directive Options:

see below

Directive Content:

none

Configuration Setting:

image_loading (only HTML5 writer)

An "image" is a simple picture:

The URI for the image source file is specified in the directive argument. As with hyperlink targets, the image URI may begin on the same line as the explicit markup start and target name, or it may begin in an indented text block immediately following, with no intervening blank lines. If there are multiple lines in the link block, they are stripped of leading and trailing whitespace and joined together.

Optionally, the image link block may contain a flat field list, the image options. For example:

Inline images can be defined with an "image" directive in a substitution definition, e.g.

means stop, means go.

The "image" directive recognizes the common options class and name as well as

align"top", "middle", "bottom", "left", "center", or "right"

The alignment of the image, equivalent to the HTML <img> tag's deprecated "align" attribute or the corresponding "vertical-align" and "text-align" CSS properties. The values "top", "middle", and "bottom" control an image's vertical alignment (relative to the text baseline); they are only useful for inline images (substitutions). The values "left", "center", and "right" control an image's horizontal alignment, allowing the image to float and have the text flow around it. The specific behaviour depends upon the browser or rendering software used.

alttext

Alternate text: a short description of the image, displayed by applications that cannot display images, or spoken by applications for visually impaired users.

heightlength

The desired height of the image. Used to reserve space or scale the image vertically. When the scale option is also specified, they are combined. For example, a height of 200px and a scale of 50 is equivalent to a height of 100px with no scale.

loading"embed", "link", or "lazy"

Set the loading attribute to indicate the preferred handling by the Docutils Writer. [4]

embed:

Embed the image into the output document. [5]

link:

Refer to the image via its URI.

lazy:

Refer to the image. The HTML5 writer additionally specifies the "lazy loading attribute".

(New in Docutils 0.21.)

scaleinteger percentage (the "%" symbol is optional)

The uniform scaling factor of the image. The default is "100 %", i.e. no scaling. Docutils tries to determine dimensions from the image file if no height or width options are specified (requires the Python Imaging Library).

targetURI or reference name

Nest the image in a hyperlink reference element (make it "clickable"). The option argument may be a URI or a reference name with underscore suffix (e.g. `a name`_).

widthlength or percentage of the current line width

The width of the image. Used to reserve space or scale the image horizontally. As with height above, when the scale option is also specified, they are combined.

[4]

Currently only recognized by the HTML5 writer (overriding the image_loading configuration setting). The ODF/ODT writer always embeds images in the *.odt document, XML and LaTeX writers link to the image. The behaviour may change for the ODT and XML writers but images cannot be embedded in a LaTeX source. [5]

SVG images are directly included, other images are base64 encoded and included as a data URI.