Gallery Setup

Galleries are the heart of Tenrankai. This guide covers everything you need to configure your image galleries.

Note: Gallery configuration lives in ConfigStorage files at config.d/sites/<site>/galleries/<name>.toml. In these files, settings are at the top level (no [[galleries]] wrapper needed). You can also create galleries via CLI: tenrankai config add-gallery <name> --site default --source <path> --url-prefix <prefix>

Basic Gallery Configuration

Each gallery is a TOML file in config.d/sites/<site>/galleries/:

# config.d/sites/default/galleries/main.toml
name = "main"                          # Unique identifier
url_prefix = "/gallery"                # URL path prefix
source_directory = "photos"            # Where your images are
cache_directory = "cache/main"         # Where processed images go
new_threshold_days = 7                 # Days to mark images as "NEW"
cache_refresh_interval_minutes = 60    # Background refresh interval

Setting	Required	Description
`name`	Yes	Unique identifier for the gallery
`url_prefix`	Yes	URL path (must start with `/`)
`source_directory`	Yes	Path to source images
`cache_directory`	Yes	Path for processed images
`new_threshold_days`	No	Mark recently modified images as NEW
`cache_refresh_interval_minutes`	No	Background metadata refresh
`grid_mode`	No	Layout mode: `masonry` or `square` (default: `masonry`)
`max_columns`	No	Maximum grid columns, 1-5 (default: `2`)

Image Sizes

Configure the dimensions for each image size:

# In your gallery TOML file (e.g., config.d/sites/default/galleries/main.toml)
[thumbnail]
width = 300
height = 300

[gallery_size]
width = 800
height = 800

[medium]
width = 1200
height = 1200

[large]
width = 1600
height = 1600

Size purposes:

thumbnail: Gallery grid previews
gallery_size: Standard viewing in gallery
medium: Detail view, optional watermarking
large: High-resolution downloads (requires permission)

All sizes automatically generate @2x variants for retina displays.

Image Quality

Control compression quality per format:

# In gallery TOML file
name = "main"
jpeg_quality = 85    # JPEG quality: 1-100 (default: 85)
webp_quality = 85.0  # WebP quality: 0.0-100.0 (default: 85.0)

Higher values = better quality but larger files. 85 is a good balance.

Image Format Support

Tenrankai automatically handles format conversion:

Source Format	Output Formats	Notes
JPEG	JPEG, WebP	WebP for supported browsers
PNG	PNG	Preserves transparency
AVIF	AVIF, WebP, JPEG	Full HDR support with gain maps

Content negotiation: Browsers that support WebP receive WebP; others get JPEG. AVIF sources are served as AVIF to capable browsers, with fallback to WebP/JPEG.

HDR and Color Profiles

Tenrankai preserves color accuracy:

ICC profiles: Maintained through all processing
Display P3: Wide gamut colors preserved
HDR AVIF: Gain maps preserved for tone mapping
10-bit encoding: HDR content encoded at proper bit depth

Watermarking

Tenrankai supports two watermark types: text-based and PNG image watermarks.

Text Watermarks

Add text watermarks with automatic color adjustment:

# In gallery TOML file
name = "portfolio"
copyright_holder = "Jane Photographer"

When set:

Watermark appears on medium-sized images by default (same sizes as PNG watermarks: apply_to_medium = true)
Text color automatically adjusts for background (black or white)
Color profiles preserved through watermarking
Requires DejaVuSans.ttf in your static directory

Both text and PNG watermarks apply to the same image sizes by default (medium only). Use the apply_to_gallery, apply_to_medium, and apply_to_large settings in the PNG watermark section to control which sizes get watermarked.

PNG Image Watermarks

Use custom PNG logos or graphics as watermarks:

# In gallery TOML file
name = "portfolio"

[image_watermark]
image = "_watermark/logo.png"    # Path relative to gallery source
position = "bottom_right"         # Where to place watermark
opacity = 0.5                     # 0.0 to 1.0 (default: 0.5)
scale = 15.0                      # Percentage of image width (1-100)
padding = 10                      # Pixels from edge (default: 10)
adaptive = true                   # Auto-invert on light backgrounds
apply_to_gallery = false          # Watermark grid view images
apply_to_medium = true            # Watermark detail view images
apply_to_large = false            # Watermark download images

Position options:

top_left, top_right, bottom_left, bottom_right - corners
center - centered on image
tiled - repeating pattern across image

Adaptive mode: Grayscale watermarks automatically invert when placed on light backgrounds, ensuring visibility. Colored watermarks are not inverted to preserve their appearance.

Watermark folder: Store watermark images in a _watermark folder in your gallery. This folder is automatically hidden from gallery navigation.

Configuring via Admin UI

Both watermark types can be configured through the Admin UI:

Go to /_admin/ → Galleries
Select your gallery
In the Watermark section:
- Toggle text watermark and enter copyright holder
- Toggle image watermark and select from available images
- Adjust position, opacity, scale, and other settings

Changes take effect immediately after saving.

Grid Modes

Control how images are laid out in the gallery grid:

# In gallery TOML file
name = "main"
grid_mode = "masonry"  # Options: masonry, square (default: masonry)
max_columns = 2        # Maximum columns displayed (default: 2)

Mode	Description
`masonry`	Variable-height layout preserving image aspect ratios (default)
`square`	Uniform square cells with images fitted inside (`contain`, not cropped)

Variable columns: The grid is responsive, scaling from 1 to 5 columns based on viewport width, capped by max_columns. The default of 2 preserves the original two-column layout.

Folder-Level Overrides

Override grid settings per folder in _folder.md frontmatter:

+++
title = "Square Gallery"
grid_mode = "square"
max_columns = 4
+++

Settings cascade: folder overrides gallery, gallery overrides defaults.

Configuring via Admin UI

Grid mode and max columns are configurable per gallery and per folder through the Admin UI at /_admin/.

Image URL Modes

Control how images are referenced in URLs:

# In gallery TOML file
name = "main"
image_indexing = "filename"  # Options: filename, sequence, unique_id

Mode	Example URL	Use Case
`filename`	`/gallery/image/IMG_1234.jpg`	SEO-friendly, debugging
`sequence`	`/gallery/image/1`	Clean URLs, portfolios
`unique_id`	`/gallery/image/a3k2x`	Privacy, client galleries

unique_id generates 6-character IDs that can’t be guessed, preventing URL enumeration.

Gallery Preview

Configure how gallery previews are generated (for homepage widgets, etc.):

[preview]
max_images = 4       # Total images to show (default: 4)
max_depth = 3        # How deep to traverse folders (default: 3)
max_per_folder = 3   # Max images from each folder (default: 3)

Custom Templates

Override default templates per gallery:

# In gallery TOML file
name = "main"
gallery_template = "modules/gallery.html.liquid"
image_detail_template = "modules/image_detail.html.liquid"

Cache Pre-Generation

Pre-generate image cache on server startup for instant loading:

[pregenerate]
formats = { jpeg = true, webp = true, avif = false }
sizes = { thumbnail = true, gallery = true, medium = true, large = false }
tiles = false

Benefits:

Parallel processing using all CPU cores
Memory-safe with concurrency limits
Incremental - only generates missing files
Graceful shutdown on Ctrl+C

When to use:

Production deployments with stable content
After adding many new images
Before launching a new gallery

High-Resolution Tile Zoom

Enable tile-based zoom for detailed image exploration:

[tiles]
tile_size = 1024  # Pixels per tile

[pregenerate]
tiles = true  # Pre-generate tiles

Tiles allow users to zoom into full-resolution details without downloading the entire large image. Users need the can_use_tile_zoom permission.

Multiple Galleries

Run multiple independent galleries from one Tenrankai instance by creating separate gallery files:

# config.d/sites/default/galleries/portfolio.toml
name = "portfolio"
url_prefix = "/"
source_directory = "/srv/photos/portfolio"
cache_directory = "/srv/cache/portfolio"
copyright_holder = "Studio Name"
image_indexing = "sequence"

# config.d/sites/default/galleries/clients.toml
name = "clients"
url_prefix = "/clients"
source_directory = "/srv/photos/clients"
cache_directory = "/srv/cache/clients"
image_indexing = "unique_id"

# config.d/sites/default/galleries/family.toml
name = "family"
url_prefix = "/family"
source_directory = "/srv/photos/family"
cache_directory = "/srv/cache/family"

Each gallery has:

Independent URL namespace
Separate cache directories
Individual permission settings
Custom templates (optional)

Folder Organization

Organize images in folders for navigation:

photos/
├── _folder.md              # Root folder description
├── 2026/
│   ├── _folder.md          # Year description
│   ├── january/
│   │   ├── _folder.md
│   │   ├── IMG_001.jpg
│   │   └── IMG_002.jpg
│   └── february/
└── portfolio/
    ├── _folder.md
    ├── headshots/
    └── landscapes/

Folder Descriptions

Add _folder.md to customize folder display:

+++
title = "Summer Vacation 2026"
hidden = false
hide_technical_details = false
grid_mode = "masonry"   # Optional: override gallery grid mode
max_columns = 3         # Optional: override gallery max columns
+++

Photos from our amazing trip to the coast.

Hidden Folders

Hide folders from navigation while keeping them accessible:

+++
title = "Private Preview"
hidden = true
+++

Hidden folders:

Don’t appear in folder listings
Are accessible via direct URL
Can be shared with specific people

Complete Gallery Example

# config.d/sites/default/galleries/portfolio.toml
name = "portfolio"
url_prefix = "/"
source_directory = "/srv/photos/portfolio"
cache_directory = "/srv/cache/portfolio"

# Display settings
new_threshold_days = 30
grid_mode = "masonry"
max_columns = 3

# Quality settings
jpeg_quality = 90
webp_quality = 90.0
copyright_holder = "Professional Photography Inc."

# Privacy
image_indexing = "sequence"

# Templates
gallery_template = "modules/gallery.html.liquid"
image_detail_template = "modules/image_detail.html.liquid"

# Image sizes
[thumbnail]
width = 400
height = 400

[gallery_size]
width = 1000
height = 1000

[medium]
width = 1600
height = 1600

[large]
width = 2400
height = 2400

# Preview widget
[preview]
max_images = 8
max_depth = 2
max_per_folder = 3

# Pre-generation
[pregenerate]
formats = { jpeg = true, webp = true, avif = false }
sizes = { thumbnail = true, gallery = true, medium = true, large = false }
tiles = false

# Enhanced zoom
[tiles]
tile_size = 1024

Permissions are configured separately in config.d/sites/default/permissions.toml:

# config.d/sites/default/permissions.toml
public_role = "viewer"
default_authenticated_role = "member"

[roles.viewer]
name = "Viewer"

[roles.viewer.permissions]
can_view = true
can_use_zoom = true

[roles.member]
name = "Member"

[roles.member.permissions]
can_view = true
can_use_zoom = true
can_download_medium = true

Next Steps

Authentication - Set up user accounts
Permissions - Control gallery access
Advanced Features - S3 storage, AI analysis