# 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:

```toml
[project.markdown_extensions]
attr_list = {}
md_in_html = {}
pymdownx.blocks.caption = {}
```

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

See additional configuration options:

- [Attribute Lists](<https://zensical.org/docs/compatibility/markdown/python-markdown/#attribute-lists>)
- [Markdown in HTML](<https://zensical.org/docs/compatibility/markdown/python-markdown/#markdown-in-html>)
- [Caption](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/#caption>)

## Usage

### Image alignment

When [Attribute Lists](<https://zensical.org/docs/compatibility/markdown/python-markdown/#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, aligned to left

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

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.

Image, aligned to right

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

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.

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.

> [!NOTE]
>
> **Why is there no centered alignment?**
>
> The [`align`](<https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#deprecated_attributes>) attribute doesn't allow for centered alignment, which is why this option is not supported by Zensical.[^/docs/authoring/images/#1] Instead, the [image captions](<#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](<https://zensical.org/docs/compatibility/markdown/python-markdown/#markdown-in-html>) extension with literal `figure` and `figcaption` tags:

Image with caption

```html
<figure markdown="span">

![Image title](https://dummyimage.com/600x400/){ width="300" }

<figcaption>Image caption</figcaption>

</figure>
```

Image caption

However, the [Caption](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/#caption>) Markdown extension provides an alternative syntax to add captions to any Markdown block element, including images:

Image with caption

```markdown
![Image title](https://dummyimage.com/600x400/){ width="300" }
/// caption
Image caption
///
```

### Image lazy-loading

Modern browsers provide [native support for lazy-loading images](<https://caniuse.com/#feat=loading-lazy-attr>) through the `loading=lazy` directive, which degrades to eager-loading in browsers without support:

Image, lazy-loaded

```markdown
![Image title](https://dummyimage.com/600x400/){ loading=lazy }
```

### Light and dark mode

If you added a [color palette toggle](<https://zensical.org/docs/setup/colors/#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, different for light and dark mode

```markdown
![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa#only-light)
![Image title](https://dummyimage.com/600x400/21222c/d5d7e2#only-dark)
```

> [!WARNING]
>
> **Requirements when using [custom color schemes](<https://zensical.org/docs/setup/colors/#custom-color-schemes>)**
>
> The built-in [color schemes](<https://zensical.org/docs/setup/colors/#color-scheme>) define the aforementioned hash fragments, but if you're using [custom color schemes](<https://zensical.org/docs/setup/colors/#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:
>
> ```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 */
> }
> ```
>
> ```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 `"custom-light"` and `"custom-dark"` to the name of your scheme.

### Lightbox and zoom

Zensical includes the [GLightbox](<https://zensical.org/docs/compatibility/mkdocs/plugins/#glightbox>) extension, which adds lightbox galleries. When enabled, clicking on an image opens it in a full-screen overlay with navigation and zoom controls.

To enable lightbox for your images, see the [GLightbox](<https://zensical.org/docs/compatibility/mkdocs/plugins/#glightbox>) setup guide.

[^/docs/authoring/images/#1]: You might also realize that the [`align`](<https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#deprecated_attributes>) 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 Zensical.