Images

The proseflyComponents() integration enables image galleries in Markdown and MDX so authors can write normal Markdown images while the site renders styled 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.

![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)

A wide valley with low clouds

The image strip keeps its horizontal layout and next-image preview. Below it, the current image’s alt text appears on the left, with left/right arrow buttons on the right. The description follows both arrow navigation and manual scrolling. Images with empty alt text have no visible description. Arrows use a disabled color and cannot be clicked when no further scrolling is possible in that direction.

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 .md and .mdx files. It generates gallery HTML while preserving the original image nodes for Astro’s image handling. The integration loads the shared CSS and client runtime; no layout imports are required.

Multi-image figures use a light-DOM <pf-image-gallery> custom element. Each gallery initializes when inserted, including after Astro page transitions, and releases scroll/button listeners, image-loading listeners, and its resize observer when removed. Reinserting a gallery preserves its scroll position. Single images remain ordinary figures, and galleries remain horizontally scrollable without JavaScript.

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>

Visible Overflow

By default, galleries keep overflowing images inside a horizontally scrollable strip. To let images extend beyond the gallery container, set overflow to "visible":

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

Visible overflow keeps the image strip layout and hides the scroll arrows. The caption shows the first image’s alt text. Ancestor elements must also allow overflow for images to extend beyond them; this mode can make the page wider than the viewport. Omit the option or use overflow="auto" to keep scrolling.

For automatically generated galleries in .md and .mdx files, configure the shared integration:

proseflyComponents({
  markdown: { imageGallery: { overflow: 'visible' } },
})

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, and also appears below multi-image galleries as the current image’s description.

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.