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, providing styles for image alignment and image captions.

Configuration

This configuration adds the ability to align images, add captions to images (rendering them as figures), and mark large images for lazy-loading. Add the following lines to mkdocs.yml:

markdown_extensions:
  - attr_list
  - md_in_html

See additional configuration options:

• Attribute Lists

• Markdown in HTML

Usage

Image alignment

When Attribute Lists 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.

??? question "Why is there no centered alignment?"

The [`align`][align] attribute doesn't allow for centered alignment, which
is why this option is not supported by Material for MkDocs.[^1] Instead,
the [image captions] syntax can be used, as captions are optional.

Image captions

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

Example:

<figure markdown> <!-- (1)! -->
  ![Placeholder](https://dummyimage.com/600x400/){ width="300" }
  <figcaption>Image caption</figcaption>
</figure>

1. :man_raising_hand: Remember to enable the Markdown in HTML extension.

Result:

![Placeholder]{ width="300" }

Image caption

Image lazy-loading

Modern browsers provide native support for lazy-loading images through the loading=lazy directive, which degrades to eager-loading in browsers without support:

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

Light and dark mode

:octicons-tag-24: Unreleased · :octicons-beaker-24: Experimental

If you added a color palette toggle and want to show different images for light and dark color schemes, you can append a #only-light or #only-dark hash fragment to the image URL:

Example:

![Placeholder light](https://dummyimage.com/600x400/f5f5f5/aaaaaa#only-light)
![Placeholder light](https://dummyimage.com/600x400/21222c/d5d7e2#only-dark)

Result:

{ width="300" } { width="300" }