# Images
Turn image-only paragraphs into styled figures and galleries.
import { Callout, Steps } from '@prosefly/astro-components';
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.
[Dahlia](https://astro-theme-dahlia.prosefly.dev/) and
[Lotus](https://astro-theme-lotus.prosefly.dev/) already register the
`proseflyComponents()` integration. The transform, styles, and runtime are active
automatically.
## What Authors Write
A paragraph that contains only one image becomes a styled figure.
```mdx
```
A paragraph that contains multiple images becomes a gallery.
```mdx
```
## 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.
```ts title="astro.config.ts"
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`.
```ts title="astro.config.ts"
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.
```mdx
import { ImageGallery } from '@prosefly/astro-components';
```
## 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.
Dahlia and Lotus already register the shared integration. Do not add another
`proseflyComponents()` instance in theme projects. For advanced manual
processor composition, add `remarkImageGallery` from the `/markdown` entry;
it injects the component import automatically.