Refactoring Markdown Gallery Processing: A Deep Dive

Date: January 8, 2026
Author: Joel Varty (with Claude Code)
Phase: 9 → 10 (Polish & Optimization)

The Problem We Were Solving

The blog system supports seven different gallery types that can be embedded in markdown using a custom syntax:

```gallery:grid

The processing pipeline had grown organically over time, with gallery parsing happening inside the main markdown processing component. While it worked, there were some issues:

1. **Tight coupling** - Gallery parsing was embedded directly in the `ReactMarkdown` components prop
2. **Complexity** - The `processMarkdown.tsx` file was handling too many concerns
3. **Poor separation** - Remark plugins and React components were mixed together
4. **Maintenance burden** - Adding new gallery features required touching the main rendering logic

## The Solution: Proper Remark Plugin Architecture

We refactored the gallery processing into a proper **Remark plugin** that follows the unified/remark ecosystem patterns.

**New file:** `src/lib/markdown/remark-gallery.ts`

The plugin uses the **visitor pattern** to walk through the markdown Abstract Syntax Tree (AST):

1. **Visit all image nodes** - Uses `unist-util-visit` to find every `image` node in the AST
2. **Check for gallery syntax** - Tests the alt text against the gallery regex pattern
3. **Extract metadata** - Parses the gallery type and optional parameters
4. **Attach data attributes** - Adds `data-*` attributes to the HTML output that React components can read

### Benefits

✅ **Separation of concerns** - Parsing is separate from rendering
✅ **Standard architecture** - Follows unified/remark ecosystem patterns
✅ **Easier to test** - Plugin can be tested independently
✅ **Extensible** - New gallery options can be added in one place
✅ **Maintainable** - Clear boundaries between different parts of the system

## Gallery Components Improvements

While refactoring the markdown processing, we also improved all seven gallery components:

1. Gallery Carousel - Added proper navigation arrow positioning
2. Gallery Grid - Optimized grid layout for various screen sizes
3. Gallery Masonry - Fixed column calculations for responsive layouts
4. Gallery Comparison - Enhanced slider interaction
5. Gallery Stacked - Improved spacing consistency
6. Gallery Thumbnail - Optimized thumbnail grid layout

## Joel's Thoughts / Reflections

_[Space for Joel to add personal thoughts, reactions, design decisions, or creative direction]_