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

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:

```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:

{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 handles the heavy lifting:

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:

<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:

```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 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:

gallery:
  dir: assets/screenshots

The get_dir_files function in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}