Images¶

While images are first-class citizens of Markdown and part of the core syntax, it can be difficult to work with them. Material for MkDocs makes working with images more comfortable by providing styles for alignment and image captions.

Configuration¶

Attribute List¶

The Attribute List extension, which is part of the standard Markdown library, allows to add HTML attributes and CSS classes to Markdown elements, and can be enabled via mkdocs.yml

markdown_extensions:
  - attr_list

Usage¶

Image alignment¶

When the Attribute List extension is enabled, images can be aligned by adding the respective alignment directions via the align attribute, i.e. align=left or align=right

![Placeholder](https://dummyimage.com/600x400/eee/aaa){ align=left }

![Placeholder](https://dummyimage.com/600x400/eee/aaa){ align=right }

If there's insufficient space to render the text next to the image, the image will stretch to the full width of the viewport, e.g. on mobile viewports.

Image captions¶

Sadly, the Markdown syntax doesn't provide native support for image captions, but it's always possible to resort to HTML. Using figure and figcaption, captions can be added to images.

Example:

<figure>
  <img src="https://dummyimage.com/600x400/eee/aaa" width="300" />
  <figcaption>Image caption</figcaption>
</figure>

Result:

Image lazy-loading¶

Modern browsers provide native support for lazy-loading images through the loading attribute, which degrades to eager-loading in browsers without support. As with image alignment, if the Attribute List extension is enabled, images can be lazy-loaded by adding loading=lazy.

Example:

![Placeholder](https://dummyimage.com/600x400/eee/aaa){ loading=lazy }

Result: