Photo Galleries

MintyFlaskSSG includes built-in photo gallery support with automatic image processing, metadata extraction, and elegant presentation. Add photos to your content using simple Markdown directives and folder-based organisation.

Introduction

The photo gallery system provides:

  • Markdown directives - Insert photos with <!--PHOTO_PLACEHOLDER_B6952D1B0BB5--> and galleries with <!--GALLERY_PLACEHOLDER_B842FB807CD9-->
  • Automatic processing - Images are resized and optimised during build
  • Folder-based galleries - Organise photos in directories, add metadata with gallery.yaml
  • Gallery index - Automatic discovery and display of all galleries
  • EXIF metadata - Camera info and settings preserved (with privacy controls)
  • PhotoSwipe lightbox - Click photos for full-screen viewing

Everything happens at build time. Your generated site contains optimised images ready for fast delivery.

Tip

**Quick Start**
  1. Put photos in data/photos/photos_original/vacation/
  2. Add to article: <!--GALLERY_PLACEHOLDER_40B7E979C53A-->
  3. Run python run.py
  4. Photos appear processed and ready

That's it! MintyFlaskSSG handles the rest.

Photo Directory Structure

Photos live in your data directory outside the Flask application:

data/
└── photos/
    ├── photos_original/       # Your original photos (input)
    │   ├── vacation/
    │   │   ├── beach.jpg
    │   │   ├── sunset.jpg
    │   │   └── gallery.yaml   # Optional metadata
    │   ├── family/
    │   │   └── reunion.jpg
    │   └── nature/
    │       └── landscape.jpg
    └── photos_processed/       # Generated sizes (output)
        ├── vacation/
        │   ├── beach_thumbnail.jpg
        │   ├── beach_article.jpg
        │   └── beach_gallery.jpg
        └── ...

Key points:

  • photos_original/ - Put your photos here. Organise in folders as you like.
  • photos_processed/ - Generated automatically. Don't edit these files.
  • Folder names become gallery names - vacation/ becomes "Vacation" gallery.
  • Any image format - JPEG, PNG, WebP, GIF all supported.

Note

The photos directory is configured in `config.py`: 
PHOTOS_LIBRARY_ROOT = str(data_dir / 'photos' / 'photos_original')
PHOTOS_OUTPUT_DIR = str(data_dir / 'photos' / 'photos_processed')

These paths use auto-discovery but can be overridden in config_local.py.

Adding Photos to Content

Use Markdown directives in your articles and pages to include photos:

Single Photo

Insert a photo with caption:

<!--PHOTO_PLACEHOLDER_AA4C83004397-->

Parameters:

  • Beach sunset - Alt text (required for accessibility)
  • photo:vacation/sunset.jpg - Path relative to photos_original/
  • "Golden hour..." - Caption (optional, appears below photo)

Result:

  • Image displayed at article size (800×600 by default)
  • Click opens in PhotoSwipe lightbox
  • Caption shown below image
  • EXIF metadata preserved (camera, settings)

Full Gallery

Display all photos from a folder:

<!--GALLERY_PLACEHOLDER_F5B4F885BC22-->

What happens:

  • All photos in vacation/ folder appear in grid layout
  • Each photo clickable for lightbox viewing
  • Title from gallery.yaml or auto-generated from folder name
  • Photos sorted alphabetically by filename

Inline Gallery

Show specific photos from a gallery:

<!--INLINE_GALLERY_PLACEHOLDER_582EB9519489-->

Format: <!--INLINE_GALLERY_PLACEHOLDER_01F1EFE630FE-->

Useful for highlighting specific photos within a larger gallery.

Gallery Index

Display a grid of all galleries:

<!--GALLERY_INDEX_PLACEHOLDER_F5705B1F20FD-->

Or filter by pattern:

<!--GALLERY_INDEX_PLACEHOLDER_110629B049BD-->
<!--GALLERY_INDEX_PLACEHOLDER_355901833E90-->

Shows:

  • Cover image for each gallery
  • Gallery title and photo count
  • Links to full gallery pages

Gallery Metadata

Add a gallery.yaml file to customise gallery display:

# data/photos/photos_original/vacation/gallery.yaml

# Display
title: "Summer Holiday 2024"
description: "Two weeks exploring coastal villages and mountain trails"

# Cover image (optional - first photo used if not specified)
cover_image: sunset.jpg

# Organisation
tags: [travel, summer, coastal]
featured: true
sort_order: 1

# Context
location: "Cornwall, UK"
author: "Your Name"

Common fields:

Field Purpose Example
title Gallery name "Summer Holiday 2024"
description Brief summary "Two weeks in Cornwall"
cover_image Thumbnail photo sunset.jpg
featured Highlight in index true
tags Categorisation [travel, summer]
sort_order Manual ordering 1

Without gallery.yaml:

  • Title auto-generated from folder name ("vacation" → "Vacation")
  • First photo used as cover
  • No description
  • Not featured

Tip

**Start simple**

Don't create gallery.yaml until you need it. The defaults work well for most galleries. Add metadata later when you want custom titles or descriptions.

Building with Photos

Photos process during the build step:

# Development server
python run.py

# Build static site
python freeze.py

What happens during build:

  1. Discovery - Scans photos_original/ for images
  2. Processing - Generates three sizes per photo:
    • Thumbnail (400×300) - Gallery grids
    • Article (800×600) - In-content display
    • Gallery (1200×800) - Lightbox viewing
  3. Optimisation - JPEG quality, progressive encoding
  4. Metadata - EXIF data extracted and cached
  5. Output - Processed images saved to photos_processed/

Build time: Varies with photo count. First build processes everything. Subsequent builds only process new/changed photos.

Cache: JSON metadata files in photos_processed/.metadata/ speed up rebuilds.

Note

**Photo Processing**

Processing happens automatically during run.py or freeze.py. You don't need special commands. Just add photos and build.

Gallery Index Pages

Create a page listing all your galleries:

---
title: Photo Galleries
status: published
---

# Photo Galleries

Browse my photography collection.

<!--GALLERY_INDEX_PLACEHOLDER_CC7EB6CF859E-->

Sorting options:

<!--GALLERY_INDEX_PLACEHOLDER_A19B0437B2CD--> # Alphabetically by title
<!--GALLERY_INDEX_PLACEHOLDER_442BAFD6B799--> # Newest photos first
<!--GALLERY_INDEX_PLACEHOLDER_0F7FE81E56DB--> # Most photos first
<!--GALLERY_INDEX_PLACEHOLDER_4D90948A52A7--> # Featured galleries first

Display options:

<!--GALLERY_GRID_PLACEHOLDER_EB1A81E96888-->

Creates a 3-column grid showing 6 travel galleries.

Common Use Cases

Blog Post with Photos

---
title: "Cornwall Coast Walk"
date: 2024-08-15
category: travel
status: published
---

Last week we explored the stunning Cornish coastline.

<!--PHOTO_PLACEHOLDER_DD9D06C23B64-->

The views were spectacular throughout the entire route.

<!--GALLERY_PLACEHOLDER_546B88B697CD-->

Photo Essay

---
title: "A Day in the Mountains"
date: 2024-07-20
category: photography
status: published
---

<!--INLINE_GALLERY_PLACEHOLDER_D49F428B5685-->

Each photo tells part of the story...

<!--PHOTO_PLACEHOLDER_CA32A85A4795-->

We started before sunrise...

Gallery Collection Page

---
title: "Travel Photography"
status: published
---

# Travel Photography

<!--GALLERY_INDEX_PLACEHOLDER_E26106351A53-->

Best Practices

Do's

✓ Use meaningful folder names - "cornwall-2024" not "photos1"

✓ Add alt text - Important for accessibility and SEO

✓ Keep original photos - photos_original/ is your archive

✓ Organise by topic - Group related photos in folders

✓ Start without gallery.yaml - Add metadata when needed

✓ Use descriptive filenames - "sunset-beach.jpg" not "IMG_1234.jpg"

Don'ts

✗ Don't edit photos_processed/ - Regenerated on each build

✗ Don't use huge originals - 4000px+ slows processing (2000px is fine)

✗ Don't nest too deeply - Keep folders 1-2 levels: travel/cornwall/ not travel/uk/cornwall/beaches/

✗ Don't skip alt text - Always provide descriptive text

✗ Don't mix photos and non-photos - Keep text files separate

Common Issues

Photos don't appear

Check:

  1. Photos in correct directory: data/photos/photos_original/folder/
  2. Markdown directive syntax: <!--GALLERY_PLACEHOLDER_AA2B686A2A96--> not <!--GALLERY_PLACEHOLDER_B18ABEF915CD-->
  3. Build completed successfully: python run.py with no errors
  4. Browser cache: Hard refresh (Ctrl+F5)

Solution:

# Clear processed photos and rebuild
rm -rf data/photos/photos_processed/*
python run.py

Gallery shows wrong photos

Problem: Inline gallery lists wrong filenames

Solution: Check exact filenames in photos_original folder:

ls data/photos/photos_original/vacation/

Use exact names including extensions in directive:

<!--INLINE_GALLERY_PLACEHOLDER_AD03BA7BE287-->

Gallery title not showing

Problem: Custom title in gallery.yaml not displaying

Solution: Ensure gallery.yaml is in the gallery folder:

data/photos/photos_original/vacation/gallery.yaml  ✓
data/photos/photos_original/gallery.yaml           ✗

And uses correct YAML syntax:

title: "My Gallery Title"    # ✓ Quoted string
title: My Gallery Title       # ✗ May cause issues

Slow build times

Problem: Processing takes too long

Solution:

  1. Resize large originals to ~2000px before adding
  2. Build processes only new/changed photos after first run
  3. Check for extremely large files: du -sh data/photos/photos_original/*

Photos look pixelated

Problem: Processed photos appear low quality

Solution: Check original photo dimensions:

identify data/photos/photos_original/vacation/photo.jpg

Ensure originals are larger than article size (800×600 default).

Quick Reference

Markdown Directives

# Single photo with caption

<!--PHOTO_PLACEHOLDER_1793B9E64D01-->

# Full gallery

<!--GALLERY_PLACEHOLDER_109EA6F71D17-->

# Specific photos only

<!--INLINE_GALLERY_PLACEHOLDER_D3C2A56AF4E9-->

# Gallery index (all galleries)

<!--GALLERY_INDEX_PLACEHOLDER_CCE1034DB6FA-->

# Gallery index (filtered)

<!--GALLERY_INDEX_PLACEHOLDER_105F0573F0C7-->
<!--GALLERY_INDEX_PLACEHOLDER_AC5F8AD41637-->

# Gallery grid with options

<!--GALLERY_GRID_PLACEHOLDER_D981B707C0E2-->

Directory Structure

data/photos/photos_original/     # Your photos go here
    └── gallery-name/
        ├── photo1.jpg
        ├── photo2.jpg
        └── gallery.yaml         # Optional metadata

gallery.yaml Template

title: "Gallery Title"
description: "Brief description"
cover_image: photo.jpg
tags: [tag1, tag2]
featured: true
location: "Place Name"

Build Commands

python run.py          # Development server
python freeze.py       # Build static site

Conclusion

MintyFlaskSSG makes photo galleries straightforward:

  1. Add photos to data/photos/photos_original/folder/
  2. Use directives in Markdown: <!--GALLERY_PLACEHOLDER_C130811FA777-->
  3. Build with python run.py or python freeze.py
  4. Optional metadata via gallery.yaml when needed

Start simple with basic galleries and add features as you need them. The system handles image processing, optimisation, and presentation automatically.

What's Next

  • Advanced Features - EXIF metadata, custom sizes, watermarking (see Advanced Photos guide)
  • Gallery Configuration - Fine-tune processing and display options
  • Template Customisation - Modify gallery layouts and styles
  • PhotoSwipe Integration - Customise lightbox behaviour

For most users, the basics covered here are sufficient. Explore advanced features when you need them.

Related Documentation:

Need Help?

  • Check photos_processed/.metadata/ for processing logs
  • Use python run.py --config photos for detailed photo logging
  • Review build output for error messages