# How to Configure Custom Image Galleries with YAML Specifications in Markdown Files

> Effortlessly configure custom image galleries in Markdown using YAML specifications. Learn how to create responsive grids and masonry layouts with Astro Big Doc for stunning visual content.

- Repository: [Micro Web Stacks/astro-big-doc](https://github.com/microwebstacks/astro-big-doc)
- Tags: how-to-guide
- Published: 2026-03-07

---

**You can configure custom image galleries in `astro-big-doc` by creating a fenced YAML code block with the `gallery` or `pz_gallery` language identifier, which automatically renders as a responsive PhotoSwipe grid or masonry layout.**

The `astro-big-doc` framework transforms simple YAML specifications into fully-featured image galleries without requiring any JavaScript configuration from content authors. By leveraging fenced code blocks in Markdown, you can define image lists or directory sources that the system automatically processes into optimized, lightbox-enabled galleries.

## Understanding the YAML Gallery Syntax

The gallery system recognizes YAML code blocks with specific language identifiers. When `astro-big-doc` encounters these blocks during Markdown processing, it intercepts them before standard code rendering and passes the YAML content to the gallery components.

### Basic Image List Syntax

To create a gallery from specific images, use a YAML array listing the filenames. The paths are relative to the directory containing the Markdown file:

```markdown

```yaml gallery
- 01 Abstract Mix.png
- 01a fail mix.png
- 12 Aqara Fan button hold.png
- 17 Retro light cable management.png
- github-dark.png

```

```

Each item in the array represents one image file. The `gallery` keyword in the code fence language slot triggers the standard gallery component.

### Directory-Based Galleries

For galleries containing all images in a folder, use the object syntax with a `dir` key:

```markdown

```yaml gallery
dir: assets/my-photos

```

```

When `yaml_to_grid_images` in [`src/components/gallery/grid_utils.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/src/components/gallery/grid_utils.js) parses this structure, it calls `get_dir_files` to read every file in the specified subdirectory under `src/content/`. This eliminates the need to manually list each filename when displaying entire directories.

## How the Gallery System Works Under the Hood

The transformation from YAML text to interactive gallery involves three main stages: detection in the Markdown pipeline, YAML parsing with image metadata extraction, and responsive layout rendering.

### Detection in Code.astro

The entry point is `src/components/markdown/code/Code.astro`, which processes every fenced code block in the Markdown AST. The component checks for gallery-specific language identifiers:

```ts
const yaml_gallery = (language == "yaml") && (node.meta?.startsWith("gallery"));
const pz_gallery = (language == "yaml") && (node.meta?.startsWith("pz_gallery"));

```

When `yaml_gallery` evaluates to true, the component renders the `<Gallery>` component instead of a standard code block, passing the raw YAML string and the page's `dirpath`:

```ts
{yaml_gallery && <Gallery code={code} dirpath={dirpath}/>}

```

### YAML Parsing and Image Processing

Inside `src/components/gallery/gallery.astro`, the helper function `yaml_to_grid_images` from [`src/components/gallery/grid_utils.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/src/components/gallery/grid_utils.js) handles the heavy lifting:

```ts
const imagesUrls = await yaml_to_grid_images(code, dirpath)

```

This function uses `yaml.load` to parse the YAML content. It then branches based on the data structure:

- **Array input**: Uses the filenames directly
- **Object with `dir` key**: Calls `get_dir_files` to enumerate the directory contents

For each image discovered, the system uses `sharp` to read dimensions and correct orientation. It calculates `spanWidth` and `spanHeight` values based on aspect ratios for the CSS Grid layout. Finally, `assetToUrl` constructs the public URL path (typically `/src/assets/...`).

### Layout Selection and Rendering

If the `masonry` prop isn't explicitly provided, the `select_masonry` function analyzes the aspect ratios of all images. When most images are wider than tall, it automatically selects a masonry layout; otherwise, it uses a standard grid.

The final rendering in `gallery.astro` produces a PhotoSwipe-compatible structure:

```astro
<div class={`pswp-gallery container ${mas?'masonry':'grid'}`} id="my-gallery">
  {imagesUrls.map(image => (
    <a href={image.url} class={`item ${mas?'masonry':'grid'}`}
       style={`grid-area: span ${image.spanHeight} / span ${image.spanWidth};`}
       data-pswp-width={image.width} data-pswp-height={image.height}>
      {image.ext == ".svg" ? <object data={image.url} /> : <img src={image.url} />}
    </a>
  ))}
</div>

```

The `data-pswp-*` attributes enable the built-in PhotoSwipe lightbox functionality, allowing users to click images for full-screen viewing with zoom capabilities.

## Advanced Gallery Configurations

Beyond the standard grid display, `astro-big-doc` supports specialized gallery variants for different presentation needs.

### Collapsible Galleries with pz_gallery

For content-heavy pages where galleries should initially hide, use the `pz_gallery` identifier:

```markdown

```yaml pz_gallery
- demo1.svg
- demo2.png
- demo3.jpg

```

```

This triggers the `GalleryPz` component from `src/components/gallery/gallery_pz.astro`. The component wraps the standard gallery in a button-controlled container that defaults to a collapsed state. Users click to expand the gallery, making this ideal for documentation pages with multiple screenshot galleries.

### Forcing Masonry Layout

While the system automatically selects between grid and masonry layouts based on image aspect ratios, you can override this behavior when using the gallery component programmatically:

```astro
<Gallery code={code} dirpath={dirpath} masonry={true} />

```

Setting `masonry={true}` forces the masonry layout regardless of the `select_masonry` logic. This is useful when you know the visual design requires a Pinterest-style layout rather than a uniform grid.

## Summary

- **YAML blocks become galleries**: Fenced code blocks with `yaml gallery` or `yaml pz_gallery` language identifiers automatically render as interactive image galleries in `astro-big-doc`.

- **Flexible input formats**: Specify images as a YAML array of filenames or use the `dir: path` object syntax to include entire directories.

- **Automatic processing**: The `yaml_to_grid_images` function in [`src/components/gallery/grid_utils.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/src/components/gallery/grid_utils.js) handles YAML parsing, image dimension extraction via `sharp`, and URL generation.

- **Smart layouts**: The system automatically chooses between grid and masonry layouts based on image aspect ratios, with optional manual override via the `masonry` prop.

- **Built-in lightbox**: All galleries include PhotoSwipe integration for full-screen viewing without additional configuration.

## Frequently Asked Questions

### How do I reference images that are in a different folder from my Markdown file?

Use the `dir` key in your YAML gallery block to specify a path relative to `src/content/`. For example, if your Markdown file is in `src/content/docs/` but your images are in `src/content/assets/screenshots/`, use:

```yaml
gallery:
  dir: assets/screenshots

```

The `get_dir_files` function in [`grid_utils.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/grid_utils.js) resolves this path against the content directory, not the Markdown file's location.

### Can I mix specific image filenames and directory sources in one gallery?

No, the YAML structure expects either an array of filenames or an object with a `dir` property. To combine specific images with directory contents, you must either list all files individually or organize them into a single directory. The `yaml_to_grid_images` function branches based on whether the parsed YAML is an array or object, handling each case separately.

### What is the difference between `gallery` and `pz_gallery`?

The `gallery` identifier renders a standard visible grid or masonry layout immediately when the page loads. The `pz_gallery` identifier triggers the collapsible version from `gallery_pz.astro`, which wraps the gallery in a container that starts collapsed with a "Click to expand" button. Use `pz_gallery` for documentation pages with multiple screenshots that shouldn't overwhelm the initial view.

### How does the system handle image orientation and aspect ratios?

The `yaml_to_grid_images` function uses the `sharp` library to read each image's metadata and automatically corrects orientation based on EXIF data. It calculates aspect ratios to determine `spanWidth` and `spanHeight` values for CSS Grid spanning. The `select_masonry` function then analyzes these aspect ratios—if most images are wider than tall, it selects a masonry layout; otherwise, it uses a uniform grid.