Images

Use rehypeImageGallery when authors should write normal Markdown images while the site renders polished figures and multi-image galleries.

What Authors Write

A paragraph that contains only one image becomes a styled figure.

![Dashboard in light mode](/images/dashboard-light.png)

A paragraph that contains multiple images becomes a gallery.

![Dashboard in light mode](/images/dashboard-light.png)
![Dashboard in dark mode](/images/dashboard-dark.png)

Standalone Astro Setup

If you are not using Lotus, add the rehype plugin in astro.config.ts.

import { defineConfig } from 'astro/config';
import {
  rehypeImageGallery,
  unified,
} from '@prosefly/astro-components/markdown';

export default defineConfig({
  markdown: {
    processor: unified({
      rehypePlugins: [rehypeImageGallery],
    }),
  },
});

Then load the gallery CSS and runtime once in the layout that renders your Markdown.

---
import '@prosefly/astro-components/markdown/image-gallery.css';
---

<slot />

<script>
  import '@prosefly/astro-components/markdown/image-gallery.js';
</script>

The JavaScript adds previous and next controls for galleries generated from multiple images. Single-image figures only need the CSS.

Authoring Rules

1. Keep gallery paragraphs image-only.

   Do not add prose, links, inline code, or captions to the same paragraph. Mixed content stays as normal Markdown.

2. Use helpful alt text.

   The transform preserves each image element. The alt text is still the main accessibility description for the image.

3. Group images intentionally.

   Put related screenshots in the same paragraph. Add a blank line before the next paragraph when a new gallery should start.