Images - Material for MkDocs (original) (raw)
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:
[](#%5F%5Fcodelineno-0-1)markdown_extensions: [](#%5F%5Fcodelineno-0-2) - attr_list [](#%5F%5Fcodelineno-0-3) - md_in_html [](#%5F%5Fcodelineno-0-4) - pymdownx.blocks.caption
See additional configuration options:
Lightbox¶
If you want to add image zoom functionality to your documentation, the glightbox plugin is an excellent choice, as it integrates perfectly with Material for MkDocs. Install it with pip:
[](#%5F%5Fcodelineno-1-1)pip install mkdocs-glightbox
Then, add the following lines to mkdocs.yml:
We recommend checking out the available configuration options.
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:
LeftRight
Image, aligned to left
[](#%5F%5Fcodelineno-3-1){ align=left }
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.
Image, aligned to right
[](#%5F%5Fcodelineno-4-1){ align=right }
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.
Why is there no centered alignment?
The 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 the Markdown in HTML extension with literal figure and figcaption tags:
Image with caption
[](#%5F%5Fcodelineno-5-1)<figure markdown="span"> [](#%5F%5Fcodelineno-5-2) { width="300" } [](#%5F%5Fcodelineno-5-3) <figcaption>Image caption</figcaption> [](#%5F%5Fcodelineno-5-4)</figure>
Image caption
However, Caption provides an alternative syntax to add captions to any Markdown block element, including images:
Image with caption
[](#%5F%5Fcodelineno-6-1){ width="300" } [](#%5F%5Fcodelineno-6-2)/// caption [](#%5F%5Fcodelineno-6-3)Image caption [](#%5F%5Fcodelineno-6-4)///
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:
Image, lazy-loaded
[](#%5F%5Fcodelineno-7-1){ loading=lazy }
Light and dark mode¶
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:
Image, different for light and dark mode
[](#%5F%5Fcodelineno-8-1) [](#%5F%5Fcodelineno-8-2)
Requirements when using custom color schemes
The built-in color schemes define the aforementioned hash fragments, but if you're using custom color schemes, you'll also have to add the following selectors to your scheme, depending on whether it's a light or dark scheme:
Custom light schemeCustom dark scheme
[](#%5F%5Fcodelineno-9-1)[data-md-color-scheme="custom-light"] img[src$="#only-dark"], [](#%5F%5Fcodelineno-9-2)[data-md-color-scheme="custom-light"] img[src$="#gh-dark-mode-only"] { [](#%5F%5Fcodelineno-9-3) display: none; /* Hide dark images in light mode */ [](#%5F%5Fcodelineno-9-4)}
[](#%5F%5Fcodelineno-10-1)[data-md-color-scheme="custom-dark"] img[src$="#only-light"], [](#%5F%5Fcodelineno-10-2)[data-md-color-scheme="custom-dark"] img[src$="#gh-light-mode-only"] { [](#%5F%5Fcodelineno-10-3) display: none; /* Hide light images in dark mode */ [](#%5F%5Fcodelineno-10-4)}
Remember to change "custom-light" and "custom-dark" to the name of your scheme.