Images

The proseflyComponents() integration enables image galleries in MDX so authors can write normal Markdown images while the site renders polished figures and multi-image galleries. Ordinary .md pages are intentionally unchanged.

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.

![A wide valley with low clouds](https://images.unsplash.com/photo-1500534314209-a25ddb2bd429?auto=format&fit=crop&w=1200&h=600&q=80)
![A vertical mountain ridge above a forest](https://images.unsplash.com/photo-1464822759023-fed622ff2c3b?auto=format&fit=crop&w=720&h=1000&q=80)
![A square waterfall in a green canyon](https://images.unsplash.com/photo-1433086966358-54859d0ed716?auto=format&fit=crop&w=900&h=900&q=80)
![A panoramic tropical coastline](https://images.unsplash.com/photo-1507525428034-b723cf961d3e?auto=format&fit=crop&w=1300&h=560&q=80)

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 adds the remarkImageGallery transform for .mdx files. It generates an ImageGallery component while preserving the original image nodes for Astro’s image handling. The component loads its own CSS and runtime only on pages that use a gallery; no layout imports are required.

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

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

Use the Component Directly

In an Astro component or MDX page, you can also import ImageGallery and provide image children explicitly. The component owns the same CSS and browser runtime as automatically generated galleries.

import { ImageGallery } from '@prosefly/astro-components';

<ImageGallery>
  ![Light mode](/images/dashboard-light.png)
  ![Dark mode](/images/dashboard-dark.png)
</ImageGallery>

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.