Images¶

While images are first-class citizens of Markdown and part of the core syntax, it can be difficult to work with them. Zensical 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 your configuration:

[project.markdown_extensions.attr_list]
[project.markdown_extensions.md_in_html]
[project.markdown_extensions.pymdownx.blocks.caption]

markdown_extensions:
  - attr_list
  - md_in_html
  - pymdownx.blocks.caption

See additional configuration options:

• Attribute Lists
• Markdown in HTML
• Caption

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:

![Image title](https://dummyimage.com/600x400/eee/aaa){ align=left }

![Image title](https://dummyimage.com/600x400/eee/aaa){ align=right }

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.

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">
  ![Image title](https://dummyimage.com/600x400/){ width="300" }
  <figcaption>Image caption</figcaption>
</figure>

However, the Caption Markdown extension provides an alternative syntax to add captions to any Markdown block element, including images:

![Image title](https://dummyimage.com/600x400/){ 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:

![Image title](https://dummyimage.com/600x400/){ 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 title](https://dummyimage.com/600x400/f5f5f5/aaaaaa#only-light)
![Image title](https://dummyimage.com/600x400/21222c/d5d7e2#only-dark)

[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 */
}

[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 */
}