mkdocs-material/docs/reference/images.md

template
overrides/main.html

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

=== "Left"

_Example_:

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

_Result_:

![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ align=left width=300 }

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.

=== "Right"

_Example_:

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

_Result_:

![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ align=right width=300 }

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.

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 caption

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:

{ loading=lazy width=300 }