Add AI documentation skills
This commit is contained in:
@@ -0,0 +1,219 @@
|
||||
---
|
||||
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
|
||||
- pymdownx.blocks.caption
|
||||
```
|
||||
|
||||
See additional configuration options:
|
||||
|
||||
- [Attribute Lists]
|
||||
- [Markdown in HTML]
|
||||
- [Caption]
|
||||
|
||||
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
||||
[Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
|
||||
[Caption]: ../setup/extensions/python-markdown-extensions.md#caption
|
||||
|
||||
### 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>
|
||||
|
||||
However, [Caption] provides an alternative syntax to add captions
|
||||
to any Markdown block element, including images:
|
||||
|
||||
``` markdown title="Image with caption"
|
||||
{ width="300" }
|
||||
/// caption
|
||||
Image caption
|
||||
///
|
||||
```
|
||||
|
||||
### 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
|
||||
Reference in New Issue
Block a user