Images

The proseflyComponents() integration enables image galleries so authors can 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 a Prosefly theme, register the shared integration in astro.config.ts. The image transform, CSS, and client runtime are enabled by default.

import { defineConfig } from 'astro/config';
import proseflyComponents from '@prosefly/astro-components/integration';

export default defineConfig({
  integrations: [proseflyComponents()],
});

The integration configures rehypeImageGallery and injects the gallery assets once for every page. No layout imports are required. The JavaScript adds previous and next controls for galleries generated from multiple images; single-image figures use the same injected CSS.

To keep the other integration features but disable galleries and their assets, set markdown.imageGallery to false.

proseflyComponents({
  markdown: { imageGallery: false },
})

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.