docs/specs/2026-09-25-gallery-design.org

• Albums from folders: photos/<album>/*.{jpg,png}, optional album.org per album.
• Pages: home, album, photo. Stable URLs.
• On-demand resize at a fixed set of widths, disk cache, srcset.
• EXIF line: camera, lens, aperture, shutter, ISO, date.
• One dark theme driven by CSS variables, overridable at runtime.
• Keyboard and swipe navigation on the photo page.
• New and changed files appear without a restart.

Private albums, upload, tags and search, RSS, likes and comments, watermarking, admin UI, WebP/AVIF derivatives, HEIC/RAW/video formats.

cmd/gallery/main.go   flags, wiring, HTTP server
internal/library/     scan photos/ into albums and items; watch for changes
internal/format/      Format interface and registry (jpeg, png)
internal/render/      derivative cache: lookup, generate, store
internal/web/         handlers, html/template pages, embedded CSS/JS

Flags, each with an environment fallback:

At startup the binary checks that magick and exiftool are on PATH and exits with a message naming whichever is missing.

type Kind int

const (
	KindImage Kind = iota
	// KindVideo later; selects a different template partial.
)

type Meta struct {
	Width, Height int // after orientation is applied
	Taken         time.Time
	Camera, Lens  string
	Aperture      string
	Shutter       string
	ISO           int
}

type Format interface {
	Name() string
	Match(path string) bool
	Metadata(path string) (Meta, error)
	Resize(src string, width int, dst io.Writer) error
	Kind() Kind
}

• A package-level registry holds formats in registration order; the first Match wins. Files no format matches are ignored.
• v1 registers jpeg (.jpg, .jpeg) and png, matched by extension, case-insensitive.

• Both share one ImageMagick-backed implementation parameterised by extensions:

  • Metadata: exiftool -json -n with the fields above. Width and height are swapped when the EXIF orientation is 5-8.
  • Resize: magick -limit memory 512MiB -limit map 1GiB <src> -auto-orient -resize <w>x -strip -quality 82 jpg:- streamed to dst. Output is always JPEG in v1.
• Adding a format (HEIC, AVIF, WebP, RAW) is a new registration. Adding video is a new Kind plus a template partial. Neither touches library or render.

• Each immediate subdirectory of -photos is an album; the slug is the directory name. Nested directories are ignored in v1. Hidden files and directories are skipped.

• album.org (optional) supplies keywords:

  #+title: Tokyo
  #+date: 2025-03
  #+cover: DSCF0412.jpg
  #+order: 10
  #+sort: taken
  

  The body, if any, is album description text rendered from org to HTML.

  • title defaults to the slug.
  • cover defaults to the first item after sorting.
  • order sorts albums ascending on the home page. Albums without it follow, newest date (else newest item taken time) first.
  • sort is taken (default) or name.
• photos/about.org (optional) is rendered as the Info page. When absent, the Info link is hidden.
• Metadata is cached in <cache>/meta.json, keyed by relative path, mtime and size. Only new or changed files are passed to exiftool.
• The library is an immutable snapshot swapped atomically behind an atomic.Pointer. fsnotify watches the root and each album directory; events are debounced (500 ms) and trigger a full rescan. Rescans are cheap because unchanged files are served from the metadata cache.
• A file that fails metadata extraction is logged and excluded.

• URL: /img/<album>/<file>/<width>.jpg.
• Allowed widths: 480, 960, 1600, 2400. Anything else is 400. Widths larger than the source are clamped to the source width.
• Cache path: <cache>/img/<album>/<file>/<mtime>-<size>/<width>.jpg. A changed source gets a new directory; stale directories are removed on the next rescan.
• Concurrent requests for the same key are collapsed with singleflight.
• Output is written to a temp file in the target directory and renamed into place, so a failed or interrupted resize never leaves a partial file.
• A process-wide semaphore caps concurrent magick runs at runtime.GOMAXPROCS(0).
• Responses carry Cache-Control: public, max-age=31536000, immutable; the URL changes when the source does because pages link with a ?v=<mtime> query.

Dark, minimal, cinematic: near-black background, light grey text, small uppercase labels with wide letter-spacing. Photos are never cropped.

Site title left; album names, Timeline and Info right, in small spaced capitals. The current page is highlighted.

Album covers laid out as justified rows (same algorithm as the album page), one cover per album, with album title and year in small capitals below each. Covers link to the album.

Title line (title left, year and count right), optional description, then all items as justified rows with a 4 px gap. No lead image. Each tile links to the photo page.

Every item from every album, newest first, grouped under month headings ("September 2025", with the item count on the right). Each month's items are justified rows linking to the item's photo page; navigation there stays within the album. Dates are Item.Taken (EXIF date, else file mtime), grouped by calendar month. timeline is a reserved album slug alongside img, info and _.

• Image fitted to the viewport (object-fit: contain), srcset over the allowed widths.
• Previous and next arrows at the sides; ← → keys and horizontal swipe navigate; Esc returns to the album. First and last items do not wrap.
• Bottom line: title or filename with position (12 / 24) on the left, EXIF line on the right. Missing EXIF fields are omitted.
• The next and previous images are preloaded.

• The server emits each item's aspect ratio as --ar (inline style) and data-ar.
• Base CSS: display: flex; flex-wrap: wrap; with each tile's width set from --row-height × --ar, so layout is uncropped and stable without JS.
• A script (target: under 50 lines) partitions items into rows whose summed aspect ratios fill the container at --row-height, sets exact heights, and recomputes on resize (debounced). The last row is not stretched.
• Width and height attributes are set on every <img> to prevent layout shift.

theme.css is embedded and replaceable with -theme. Variables:

Templates (base, home, album, photo, info, error) are embedded and replaceable with -templates.

album.org bodies and about.org are rendered with github.com/niklasfasching/go-org.