Images

The .. image:: directive puts a picture on the page with no caption. Its argument is a path relative to this document, a path from the source root (with a leading /), or an external URL.

A bare image

Alternative text

:alt: is what a screen reader announces. Writing :alt: with no value is the deliberate spelling for a picture that carries no information of its own.

Sizing

:width: takes a length or a percentage; :height: takes a length only.

:scale: multiplies whatever :width: and :height: were given.

Alignment

:align: left and :align: right float the picture, which means the text that follows flows around it rather than starting below it. That is what alignment is for, so each example below is followed by enough prose to show the wrapping.

Floated to the left, so this paragraph wraps around its right-hand side. A floated image is taken out of the normal flow of the page: the text does not begin below it, it begins beside it, and only returns to the full width of the page once it has passed the bottom of the picture. Notice that the heading below still starts on a clean line — headings clear any float still standing, so one section's picture can never intrude into the next.

Centre alignment

:align: center does not float. The image stays in the normal flow as a block of its own, centred between the margins, and the text resumes below it.

This paragraph starts below the centred picture rather than beside it, which is the whole difference between centring and floating.

Right alignment

Floated to the right, so this paragraph wraps around its left-hand side. Two images aligned to the same side stack one below the other rather than sitting side by side, and a centred image between them starts below the float rather than riding up alongside it — both of which depend on the clear rules in the stylesheet.

Making the image a link

:target: accepts a URL, or the name of a target elsewhere in the project written with a trailing underscore.

This paragraph is a link target, and the next image points at it.

Referring to an image

:name: makes the image itself a target, so the-logo reaches it.

Classes

:class: puts extra class names on the <img> element.

How the bytes reach the page

:loading: chooses between three answers. link is the default: the page points at the bundled file.

lazy links the same way, and additionally sets HTML's own loading="lazy" attribute so the browser can defer fetching the picture until it is nearly on screen.

embed puts the file's bytes into the page itself as a data: URI, so the page needs no second request — and no second file — to show it.

An external image

An absolute URL is passed through untouched. Nothing is bundled for it and nothing is validated, since the file is not part of this project.

A source-root-relative path

A leading / resolves from the top of the documentation source tree rather than from this document's own directory, which is what lets a deeply nested page name a shared asset without counting ../ segments.