f82a345f3a
* Updated images documentation to include pymdownx.blocks.caption extension * put back HTML figure in image caption docs * fix typo in image captions
6.8 KiB
| icon |
|---|
| material/image-frame |
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
- 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:
pip install mkdocs-glightbox
Then, add the following lines to mkdocs.yml:
plugins:
- glightbox
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:
=== "Left"
``` markdown title="Image, aligned to left"
{ align=left }
```
<div class="result" markdown>
{ 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.
</div>
=== "Right"
``` markdown title="Image, aligned to right"
{ align=right }
```
<div class="result" markdown>
{ 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.
</div>
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 the Markdown in HTML extension with literal
figure and figcaption tags:
<figure markdown="span">
{ width="300" }
<figcaption>Image caption</figcaption>
</figure>
However, Caption provides an alternative syntax to add captions to any Markdown block element, including images:
{ width="300" }
/// caption
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:
{ 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:
{ width="300" }
{ width="300" }
!!! warning "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 scheme"
``` css
[data-md-color-scheme="custom-light"] img[src$="#only-dark"],
[data-md-color-scheme="custom-light"] img[src$="#gh-dark-mode-only"] {
display: none; /* Hide dark images in light mode */
}
```
=== "Custom dark scheme"
``` css
[data-md-color-scheme="custom-dark"] img[src$="#only-light"],
[data-md-color-scheme="custom-dark"] img[src$="#gh-light-mode-only"] {
display: none; /* Hide light images in dark mode */
}
```
Remember to change `#!css "custom-light"` and `#!css "custom-dark"` to the
name of your scheme.