mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-12-30 00:03:23 +01:00
207 lines
6.5 KiB
Markdown
207 lines
6.5 KiB
Markdown
---
|
||
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
|
||
|
||
### Lightbox
|
||
|
||
<!-- md:version 0.1.0 -->
|
||
<!-- md:plugin [glightbox] -->
|
||
|
||
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`:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- glightbox
|
||
```
|
||
|
||
We recommend checking out the available
|
||
[configuration options][glightbox options].
|
||
|
||
[glightbox]: https://github.com/blueswen/mkdocs-glightbox
|
||
[glightbox options]: https://github.com/blueswen/mkdocs-glightbox#usage
|
||
|
||
## 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="span">
|
||
{ 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
|
||
|
||
<!-- md:version 8.1.1 -->
|
||
|
||
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>
|
||
|
||
!!! 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.
|
||
|
||
[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
|
||
[color schemes]: ../setup/changing-the-colors.md#color-scheme
|
||
[custom color schemes]: ../setup/changing-the-colors.md#custom-color-schemes
|