mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-12-13 00:01:17 +01:00
155 lines
5.0 KiB
Markdown
155 lines
5.0 KiB
Markdown
---
|
||
template: overrides/main.html
|
||
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`:
|
||
|
||
``` yaml
|
||
markdown_extensions:
|
||
- attr_list
|
||
- md_in_html
|
||
```
|
||
|
||
See additional configuration options:
|
||
|
||
- [Attribute Lists]
|
||
- [Markdown in HTML]
|
||
|
||
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
||
[Markdown in HTML]: ../setup/extensions/python-markdown.md#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"
|
||
|
||
``` 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.
|
||
|
||
[^1]:
|
||
You might also realize that the [`align`][align] attribute has been
|
||
deprecated as of HTML5, so why use it anyways? The main reason is
|
||
portability – it's still supported by all browsers and clients, and is very
|
||
unlikely to be completely removed, as many older websites still use it. This
|
||
ensures a consistent appearance when a Markdown file with these attributes
|
||
is viewed outside of a website generated by Material for MkDocs.
|
||
|
||
[align]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#deprecated_attributes
|
||
[image captions]: #image-captions
|
||
|
||
### 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:
|
||
|
||
``` html title="Image with caption"
|
||
<figure markdown>
|
||
{ width="300" }
|
||
<figcaption>Image caption</figcaption>
|
||
</figure>
|
||
```
|
||
|
||
<div class="result">
|
||
<figure>
|
||
<img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" />
|
||
<figcaption>Image caption</figcaption>
|
||
</figure>
|
||
</div>
|
||
|
||
### Image lazy-loading
|
||
|
||
Modern browsers provide [native support for lazy-loading images][lazy-loading]
|
||
through the `loading=lazy` directive, which degrades to eager-loading in
|
||
browsers without support:
|
||
|
||
``` markdown title="Image, lazy-loaded"
|
||
{ loading=lazy }
|
||
```
|
||
|
||
<div class="result" markdown>
|
||
<img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" />
|
||
</div>
|
||
|
||
[lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr
|
||
|
||
### Light and dark mode
|
||
|
||
[:octicons-tag-24: 8.1.1][Light and dark mode support] ·
|
||
: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:
|
||
|
||
``` markdown title="Image, different for light and dark mode"
|
||
|
||
|
||
```
|
||
|
||
<div class="result" markdown>
|
||
|
||
![Zelda light world]{ width="300" }
|
||
![Zelda dark world]{ width="300" }
|
||
|
||
</div>
|
||
|
||
|
||
[Light and dark mode support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.1
|
||
[color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
|
||
[Zelda light world]: ../assets/images/zelda-light-world.png#only-light
|
||
[Zelda dark world]: ../assets/images/zelda-dark-world.png#only-dark
|