immich-folio/docs/gallery-config.md

# Gallery Configuration

Configuration is split across two files in `content/`:

| File            | Contains                                                                     |
| --------------- | ---------------------------------------------------------------------------- |
| `gallery.yaml`  | **Structure** — hero assets, albums, subpages, sections, per-album settings  |
| `settings.yaml` | **Behaviour and identity** — title, theme, grid defaults, footer, legal, SEO |

Copy the examples to get started:

```bash
cp content/gallery.yaml.example content/gallery.yaml
cp content/settings.yaml.example content/settings.yaml
```

`settings.yaml` is optional — without it, everything falls back to defaults.

> [!TIP]
> Prefer a visual interface? Enable the **[Admin Panel](admin-panel.md)** by setting `ADMIN_PASSWORD` in your environment. It provides a drag-and-drop page builder that writes to these same YAML files automatically.

**Contents:**

`gallery.yaml`

- [Hero Images](#hero-images)
- [Standalone Albums](#standalone-albums)
- [Subpages & Categories](#subpages)
- [Per-Album Options](#per-album-options)
- [Photo Order Within an Album](#photo-order-within-an-album)

`settings.yaml`

- [Grid Layout](#grid-layout)
- [Site Behaviour](#site-behaviour)
- [Navigation Links](#navigation-links)
- [Client Proofing](#client-proofing)
- [Client Proofing Links](#client-proofing-links)
- [Photo Zoom](#photo-zoom)
- [Image Protection & Watermark](#image-protection--watermark)
- [SEO](#seo)
- [Footer](#footer)

Other

- [About Page](#about-page)
- [Journal & Photo Essays](journal.md)
- [Finding UUIDs](#finding-uuids)
- [System & Security](#system--security)

## Hero Images

Single image or crossfade carousel on the homepage:

```yaml
# Single hero image
hero: 00000000-0000-0000-0000-000000000000

# Carousel (crossfade between multiple images)
hero:
  - 00000000-0000-0000-0000-000000000000
  - 11111111-1111-1111-1111-111111111111
  - 22222222-2222-2222-2222-222222222222
```

## Standalone Albums

Albums shown directly on the homepage as cards.

> [!NOTE]
> The thumbnail image for each album grid card is automatically synced with the explicit **\"Cover Image\"** you select for that album inside the Immich Web UI.

```yaml
albums:
  - 11111111-1111-1111-1111-111111111111
  - 22222222-2222-2222-2222-222222222222
```

## Subpages

Group multiple albums into named collections. URLs are auto-generated from the name.
The overall **Subpage Cover Image** shown on the homepage is automatically inherited from the Cover Image of the **first album** inside its list.

```yaml
subpages:
  - name: Japan # → /japan
    title: 'Trip to Japan' # Optional: overrides the page heading
    subtitle: '2024 adventures' # Optional: adds a subline under the heading
    albums:
      - 33333333-3333-3333-3333-333333333333 # Tokyo
      - 44444444-4444-4444-4444-444444444444 # Kyoto

  - name: Wedding – Smith # → /wedding-smith
    password: clientpass123 # Optional: subpage-level protection
    albums:
      - 55555555-5555-5555-5555-555555555555
      - 66666666-6666-6666-6666-666666666666:
          title: 'Private Highlights'
          password: 'album-secret-123' # Optional: album-level protection
```

Alternatively, you can use the object notation (recommended):

```yaml
subpages:
  'Japan':
    title: 'Trip to Japan'
    subtitle: '2024 adventures'
    albums:
      - 33333333-3333-3333-3333-333333333333
```

### Subpage Options

| Key         | Type    | Description                                                                                      |
| ----------- | ------- | ------------------------------------------------------------------------------------------------ |
| `name`      | string  | Navigation label; the URL slug is derived from it                                                |
| `title`     | string  | Page heading, defaults to `name`                                                                 |
| `subtitle`  | string  | Subline under the heading                                                                        |
| `password`  | string  | Gates the whole subpage — see [Password Protection](#password-protection)                        |
| `albums`    | list    | Album UUIDs, optionally with [per-album options](#per-album-options)                             |
| `sections`  | list    | Named groups of albums — see [Sections](#sections)                                               |
| `grid`      | object  | Grid override for the photos on this page — see [Grid Layout](#grid-layout)                      |
| `coverGrid` | object  | Grid override for the album covers on this page — see [Album covers](#album-covers-on-a-subpage) |
| `proofing`  | boolean | Enables [client proofing](#client-proofing) on this page                                         |
| `zoom`      | boolean | [Photo zoom](#photo-zoom) for the albums on this page, over the site setting                     |
| `essayFile` | string  | Render a Markdown essay instead of a grid — see [Journal & Photo Essays](journal.md)             |
| `essayText` | string  | Essay Markdown inline; written by the admin block editor                                         |
| `enabled`   | boolean | `false` takes the page offline without deleting it                                               |
| `hidden`    | boolean | **Experimental.** Reachable by direct link, but hidden from the navigation                       |

```yaml
subpages:
  - name: Client Preview
    hidden: true # unlisted: not in the nav, still reachable at /client-preview
    proofing: true # visitors can mark favourites and export the selection
    password: 'clientpass123'
    albums:
      - 55555555-5555-5555-5555-555555555555

  - name: Old Series
    enabled: false # offline, keeps its configuration
    albums:
      - 66666666-6666-6666-6666-666666666666
```

> [!NOTE]
> `hidden` is unlisting, not access control. The URL is guessable — a slug is
> derived from the name — and nothing stops a visitor who has it. Combine it
> with `password` for anything that must stay private.

### Sections

When a subpage contains many albums you can split them into **named sections**. A typographic table of contents with anchor links is automatically rendered above the albums. Sections are fully optional — omit them and you get the standard flat grid.

Each section can have:

| Field         | Type   | Required | Description                                 |
| ------------- | ------ | -------- | ------------------------------------------- |
| `title`       | string | ✅       | Section heading + anchor name               |
| `description` | string | ➖       | Optional subline under the heading          |
| `albums`      | list   | ✅       | Album UUIDs (same format as regular albums) |

Within the `albums` list you can use a plain UUID, a simple title override, or an object — see [Per-Album Options](#per-album-options).

**Full example:**

```yaml
subpages:
  - name: Japan
    title: Japan
    subtitle: 'Travel through a land full of contrasts.'
    sections:
      - title: Tokyo
        description: 'Megacity, neon lights, silence in the noise.'
        albums:
          - '33333333-3333-3333-3333-333333333333'
          - '44444444-4444-4444-4444-444444444444': Shinjuku at night

      - title: Kyoto
        description: 'Temples and bamboo forests.'
        albums:
          - '55555555-5555-5555-5555-555555555555': Fushimi Inari
          - '66666666-6666-6666-6666-666666666666'

      - title: Osaka
        albums: # description is optional
          - '77777777-7777-7777-7777-777777777777'
```

> [!NOTE]
> Each section title is automatically converted to a URL-safe anchor (`#tokyo`, `#kyoto`, …). The TOC appearance (separator character, numbering style, section rule) is fully controlled by the active theme.

## Per-Album Options

Every album entry — standalone, on a subpage, or inside a section — accepts the
same three notations:

```yaml
albums:
  - 'album-uuid' # → uses the Immich album name
  - 'album-uuid': My Title # → displays "My Title" instead
  - 'album-uuid':
      title: My Private Title
      description: 'Shot on 35mm film in Vienna, spring 2025.'
      password: 'secure-password'
      heroImage: 'asset-uuid'
      sort: filename
      download: true
```

| Key             | Description                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| `title`         | Display name instead of the Immich album name                                 |
| `description`   | Shown below the album title                                                   |
| `password`      | Gates this album alone — see [Password Protection](#password-protection)      |
| `heroImage`     | Asset UUID overriding the album cover                                         |
| `sort`          | Photo order — see [Photo Order Within an Album](#photo-order-within-an-album) |
| `assetOrder`    | Pinned asset UUIDs for `sort: manual`                                         |
| `grid`          | **Experimental.** Grid override for this album only                           |
| `coverPosition` | **Experimental.** Focal point for the cover crop                              |
| `download`      | Offer originals for download — see [Originals download](#originals-download)  |
| `zoom`          | [Photo zoom](#photo-zoom) for this album, over its page and the site setting  |

### Per-album grid (experimental)

An album can override the grid it is shown in. It is merged over the subpage
grid, which is merged over the global default — so an album only has to state
what differs:

```yaml
albums:
  - 'album-uuid':
      title: Panoramas
      grid:
        layout: justified
        columns: 2
```

### Cover focal point (experimental)

Album covers are cropped to the card. `coverPosition` decides which part
survives the crop — the same values CSS `object-position` takes:

```yaml
albums:
  - 'album-uuid':
      coverPosition: '50% 25%' # or: "top", "center bottom", "left"
```

Useful when the automatic centre crop cuts off a horizon or a face.

### Originals download

Opt in per album with `download: true`. Off everywhere by default, and opt-in
on purpose: a public portfolio should not start handing out full-resolution
originals because one client gallery needed to.

```yaml
albums:
  - 'album-uuid':
      download: true
```

The API key needs the `asset.download` permission in Immich, since originals
are streamed from `/assets/:id/original`.

Once enabled, visitors get a **Download album** link in the album header (every
original as a ZIP), and — where [client proofing](#client-proofing) is on — a
**Download selected (.zip)** action in the export dialog that zips just the
favourited photos.

The download route re-checks the allowlist, the `download` flag, every password
gate on a route to the album, and that each asset really belongs to that album,
so an edited URL cannot reach anything else. The ZIP keeps the original
filenames (deduplicated on collision) and is streamed, so album size does not
drive memory use.

Originals keep their metadata except their location. JPEG, HEIC/HEIF and AVIF
files are delivered with camera, lens, exposure, copyright/IPTC and colour
profile intact, but with GPS coordinates removed from EXIF and XMP; the image
data itself is not touched. Other formats (RAW, DNG, PNG, TIFF, WebP, video) are
delivered exactly as Immich stores them, including any GPS. The diagnostics page
warns when a download album contains such files.

A photo edited in Immich's own editor (crop, rotate) is downloaded as edited,
not as the camera file. Immich renders the edit as a full-resolution JPEG
without EXIF, so that file has no camera data either, and its name gets a
`.jpg` extension (`IMG_0001.HEIC` arrives as `IMG_0001.jpg`). It passes the
same location scrubber.

One visitor (by client IP, see `TRUSTED_PROXY_HOPS`) can have at most two ZIPs
downloading at once, album and proofing downloads counted together; a third
gets a "too many requests" page until one finishes. A ZIP whose download stops
reading for 60 seconds is closed, so an abandoned or stalled download does not
hold its connection to Immich open.

## Password Protection

A password can be set on the whole site, on a subpage, on a single album, and on
a [journal entry](journal.md#password-protected-entries). Unlocking sets an
`HttpOnly` cookie that is valid for 24 hours; nothing is stored server-side.

Three storage formats are accepted:

| Format             | Status                                                                |
| ------------------ | --------------------------------------------------------------------- |
| `scrypt:salt:hash` | **Recommended.** The password is not recoverable from `gallery.yaml`. |
| Plaintext          | Works, but deprecated — logs a warning naming the recommended hash.   |
| bcrypt (`$2a$…`)   | Rejected.                                                             |

To get the hash for an existing plaintext password, unlock the gallery once and
read the server log: the successful unlock prints the matching `scrypt:…` line
to paste back into `gallery.yaml`. Simpler: open the page or album in the
admin panel and save it once. Every password saved there is stored as a
`scrypt:…` hash, and the field then reads **Protected** with **Change** and
**Remove** instead of showing the stored value.

> [!NOTE]
> Album and subpage gates protect the **page**. Image URLs handed out while a
> gallery was unlocked keep working — see
> [Image Token Revocation](#image-token-revocation).

### Locking the whole site

`sitePassword` in `settings.yaml` puts everything public behind one password —
useful while a portfolio is still being built, or for a folio that is only ever
shown to clients.

```yaml
# settings.yaml
sitePassword: 'scrypt:...'
```

`SITE_PASSWORD` in the environment overrides the file, so the password can be
rotated without editing (or backing up) `settings.yaml`. It accepts the same
three storage formats as every other gate.

Unlike the per-page gates, this one is enforced in `proxy.ts`, before the
requested page renders at all. That matters: a gate that merely swapped the page
for a login form would still have let the page produce its payload, album names
and image tokens included. The public API routes carry the same check
themselves, since route handlers do not pass through the proxy.

These stay reachable on a locked site:

| Path                       | Why                                                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/health`              | A health probe runs without cookies; gating it takes the container down.                                                              |
| `/admin`                   | It has its own password, and it is where `sitePassword` is set.                                                                       |
| `/install`                 | A fresh deployment has to be configurable before it can be locked.                                                                    |
| `/impressum`, `/privacy`   | The password page is public and links them; a German Impressum must be reachable directly. Neither shows an album or the site's menu. |
| `/contact`, `/api/contact` | The Impressum links the form as its second contact channel. Honeypot, fill-time check and rate limit apply as on an open site.        |

A legal or contact page that is switched off is still a 404 on a locked site.

A locked site also serves `noindex, nofollow` regardless of the SEO settings —
there is nothing there for a crawler.

## Photo Order Within an Album

By default a Folio album mirrors the Immich timeline. That is usually right, but a curated series has a narrative order that has nothing to do with capture time — and changing the sort on the Immich album would change it for the archive too. The optional `sort` key decouples the two.

| Mode       | Order                                                                                   |
| ---------- | --------------------------------------------------------------------------------------- |
| `immich`   | Default. Inherits the album's own `asc`/`desc` setting in Immich.                       |
| `newest`   | Capture time, newest first, regardless of the Immich setting.                           |
| `oldest`   | Capture time, oldest first.                                                             |
| `filename` | `originalFileName` in natural order — `IMG_2` before `IMG_10`.                          |
| `manual`   | Pinned photos first, in the order you set; everything else follows in the Immich order. |

```yaml
albums:
  - 'album-uuid' # no sort key → Immich order, exactly as before
  - 'album-uuid':
      sort: filename # an entry may carry only a sort, with no title override
  - 'album-uuid':
      title: Hokkaido, in sequence
      sort: manual
      assetOrder: # pinned, in this order
        - 'asset-uuid-opening-frame'
        - 'asset-uuid-second-frame'
```

`sort` works the same on standalone, subpage and section albums.

### About `manual`

`manual` is a pinned **prefix**, not a full permutation: `assetOrder` lists only the photos you placed by hand, and everything else follows in the album's Immich order. Curating an opening sequence therefore costs a handful of UUIDs rather than one per photo in the album.

This also makes the album resilient to changes in Immich. Photos removed from the album are ignored, and photos added later appear at the end rather than being hidden — so `gallery.yaml` never has to be kept in sync by hand.

The `/admin` page builder has a drag & drop editor for this (album → **Photo order** → **Manual** → **Reorder photos**), which is considerably easier than writing asset UUIDs by hand. It only writes a cleaned-up `assetOrder` when you explicitly apply it.

> [!NOTE]
> Two consequences worth knowing. On a subpage with several albums, `sort` orders photos _within_ each album — the albums themselves stay in the order they are listed in. And lightbox permalinks (`#photo-3`) are positional, so changing an album's sort moves where a previously shared link lands.

> [!TIP]
> `immich` means "inherit the album's sort setting from Immich", which is capture-time order in one direction or the other. It is not the manual drag order from the Immich web UI — Immich does not expose that order through its API, so Folio cannot reproduce it. Use `manual` for a hand-picked sequence.

## Grid Layout

The global default lives in `settings.yaml`; subpages and individual albums can
override it in `gallery.yaml`. The three levels merge, most specific winning:

**global (`settings.yaml`) → subpage → album**

> [!NOTE]
> Leaving `gap` out is not the same as setting `12`. Each theme preset picks its
> own photo spacing (2px `minimal`, 32px `editorial`, 40px `monograph`), and an
> unset `gap` lets that stand. Setting one wins in every preset — which is what
> `minimal`, `editorial` and `monograph` used to ignore
> ([#513](https://github.com/ralksta/immich-folio/issues/513)).

```yaml
# settings.yaml — global defaults
grid:
  columns: 3 # number of columns (default: 3)
  gap: 12 # gap in pixels — unset means the theme preset decides
  aspectRatio: '1' # "1", "3/2", "2/3", "16/9", "auto" (default: "1")
  layout: masonry
```

```yaml
# gallery.yaml — per-subpage override
subpages:
  - name: Japan
    grid:
      columns: 4
      layout: uniform
      aspectRatio: '3/2'
    albums:
      - '33333333-3333-3333-3333-333333333333'
```

Available layouts: `masonry`, `uniform`, `showcase`, `filmstrip`,
`editorial-flow`, `justified` (experimental), and `essay`
(see [Journal & Photo Essays](journal.md)). Each is illustrated in the
**[Theming guide](theming.md#gridlayout)**.

### Album covers on a subpage

A subpage with more than one album shows a grid of album covers rather than
photos. That grid has its own key, `coverGrid`, which sizes the cover tiles and
nothing else. `grid` next to it stays what it always was: the photos inside
those albums.

An unset `columns` falls back to the site-wide `grid.columns`, so a page that
states nothing tiles its covers the way it tiles its photos. Valid range is 1–6;
below 1024px viewport width at most two covers share a row, and below 640px they
stack.

`gap` is the deliberate exception: it does **not** cascade from the global
setting to the covers. Every theme preset picks its own cover spacing as part of
its look — 1px in `monograph`, 2px in `minimal` and `editorial`, 20px in
`studio-modern` — and letting the site-wide photo gap through would flatten all
of them into one look. Only an explicit `coverGrid.gap` overrides the preset:

```yaml
# gallery.yaml — the two grids of one page, set independently
subpages:
  - name: Editorial
    coverGrid:
      columns: 3 # three covers per row (site-wide default otherwise)
      gap: 24 # overrides the theme's own cover spacing
    grid:
      columns: 4 # the photos inside each album
      gap: 6
    albums:
      - '33333333-3333-3333-3333-333333333333'
      - '44444444-4444-4444-4444-444444444444'
```

Both are editable per page in the admin panel, under **Pages › _subpage_ ›
Album Cover Grid** and **Photo Grid**; left empty they follow the site-wide
setting and the theme respectively.

> [!NOTE]
> The covers and the photos shared a single `grid` key until
> [#523](https://github.com/ralksta/immich-folio/issues/523), where a gap typed
> into the admin's cover field turned out to retune every photo grid on the page
> as well. A `gallery.yaml` that predates the split has no `coverGrid`, so the
> covers fall back to `grid` and the page renders exactly as before; the first
> save from the admin panel writes the two out separately.

## Site Behaviour

Feature toggles in `settings.yaml`:

```yaml
title: 'My Portfolio'
subtitle: 'A visual journal'
lang: 'en'

mode: dark # dark (default) | light | auto — what a first-time visitor sees
exifOnHover: true # the summary overlay on photo grid hover
exif: # which groups may be shown at all
  camera: true # body, lens, focal length
  settings: true # aperture, shutter speed, ISO
  location: true # city and country
  caption: true # the description written in Immich
map: true # the interactive world map at /map
transitions: true # smooth page transitions between routes
scrollToTop: true # floating back-to-top arrow on long pages
analytics: true # cookieless view counts, see below
zoom: false # 1:1 zoom in the lightbox, see Photo Zoom

about:
  enabled: true # the /about page, rendered from content/about.md
```

| Key             | Default | Notes                                       |
| --------------- | ------- | ------------------------------------------- |
| `lang`          | `en`    | Interface language, `<html lang>`, dates    |
| `mode`          | `dark`  | Visitor's starting colour mode, see below   |
| `exifOnHover`   | on      | The grid hover overlay only, see below      |
| `exif.*`        | on      | Per-group EXIF visibility, see below        |
| `map`           | **off** | Opt-in: must be set to `true` explicitly    |
| `transitions`   | on      |                                             |
| `scrollToTop`   | on      |                                             |
| `analytics`     | on      |                                             |
| `zoom`          | **off** | Opt-in, see [Photo Zoom](#photo-zoom)       |
| `about.enabled` | on      | Needs a `content/about.md` to show anything |

### Colour mode

`mode` decides what a visitor sees before they touch anything: `dark` (the
default the site has always had), `light`, or `auto` to follow their operating
system. It is rendered onto `<html>` server-side, so the first paint is already
right rather than flipping after the page loads.

A visitor's own choice from the header toggle is kept in their browser and
always wins over this — `mode` only sets the starting point. The light/dark
switch in the admin panel previews _your_ view and does not change what
visitors get; that is what this setting is for
([#512](https://github.com/ralksta/immich-folio/issues/512)).

### EXIF visibility

`exif` decides what the site may publish about a photo. It governs all three
places the data appears — the grid hover overlay, the lightbox info panel, and
the camera line in the album header — so they cannot disagree.

`caption` is the description written in Immich. It used to be shown regardless
of any setting, on the grounds that a caption is editorial rather than
metadata — which left it as the one field nobody could switch off, and Immich
descriptions are also where people keep private notes and whatever a decade of
cataloguing software left behind ([#506](https://github.com/ralksta/immich-folio/issues/506)).
It is a group like any other now.

`exifOnHover` predates the block and stays: it decides whether the grid shows
its overlay at all, and it supplies the default for the three technical groups,
so an existing `exifOnHover: false` still means "no technical EXIF anywhere". An
explicit `exif` key always wins over it. Captions never followed that switch and
still do not — set `caption: false` to turn them off.

With every group off, the lightbox withdraws its info button and the `i` key
rather than opening an empty panel.

### Interface language

`lang` picks the language of the visitor-facing interface — navigation, the
lightbox, the password gate, the proofing dialog, the legal notice, error pages
— and is also emitted as `<html lang>` and used for date formatting.

| Value | Interface         |
| ----- | ----------------- |
| `en`  | English (default) |
| `de`  | German            |
| `fr`  | French            |
| `es`  | Spanish           |
| `it`  | Italian           |
| `nl`  | Dutch             |

Region subtags are accepted and dropped for the interface (`fr-CA` → French,
`nl-BE` → Dutch), while the full value still reaches `<html lang>`.

Any other value (`ja`, `pt`, …) still reaches `<html lang>` and
`toLocaleDateString`, but the interface stays English: there is no dictionary
for it yet. That is deliberate — claiming `lang="en"` on a French site would be
worse for screen readers than an English interface on a page correctly marked
as Japanese.

Two things stay in one language by design:

- **The admin panel** is always English, whatever `lang` says.
- **`/impressum`** keeps its German headings when `lang: de` and the § 5 DDG
  citation in every language, because that is what the statute names
  (`legal.heading` replaces it where another law applies). Under `lang: en`
  the footer link reads "Legal Notice" rather than "Impressum" — the page is
  optional (`legal.enabled`), and an unexplained German word in the footer of
  an English site is what drove this out of the backlog.

Adding a language means adding one file under `lib/i18n/locales/` and listing
it in `SUPPORTED_LOCALES` (`lib/i18n/index.ts`). The dictionary is typed
against the English one, so a missing key fails the type-check rather than
falling back silently, and `lib/__tests__/i18n.test.ts` additionally catches
keys that were copied over but never translated. Words a language genuinely
shares with English (`ISO`, `Info`, French "photos") go into that locale's
allowance list in the same test, which in turn fails if an entry stops being
identical. Add the language to the **Language** select in
`app/admin/components/SettingsEditor.tsx` so it can be picked from the admin
panel.

### Analytics

Page and album view counts, stored in `content/analytics.json` — no cookies, no
third party, nothing leaving your server. The numbers are shown in the admin
panel's **Analytics** tab.

```yaml
analytics: false # stop counting entirely
```

With `analytics: false` the tracking endpoint refuses to record, so no data is
collected regardless of what the browser sends.

## Navigation Links

**Experimental.** External links appended to the header navigation. Only
`http(s)` URLs are accepted, and they open in a new tab:

```yaml
navLinks:
  - label: 'Shop'
    url: 'https://shop.example.com'
  - label: 'Instagram'
    url: 'https://instagram.com/your-handle'
```

## Client Proofing

Lets a visitor mark favourites and export the selection — for handing a client a
gallery and getting their picks back. A heart button sits on every photo in the
grid; once something is picked, a bar appears with a filter and an export
dialog.

The selection is encoded into the URL as a compact bitmask and mirrored into
`localStorage`, so **nothing is stored server-side** and a set of picks can be
shared, bookmarked, or sent back as a plain link.

When an album also opts into [originals download](#originals-download), the
export dialog gains a **Download selected (.zip)** action, and the album header
a **Download album** link.

Configured in `settings.yaml`:

```yaml
proofing:
  enabled: true # hearts, selection bar and export modal (default: true)
  allowMailto: true # offer "send by email" alongside the copyable list (default: true)
  email: proofs@example.com # recipient of that email (default: footer.email)
```

The email draft goes to `proofing.email`, or to the footer contact email
(`footer.email`) when that is unset. With neither configured the dialog hides
the email button rather than opening a draft with an empty **To:**. The address
is set in the admin panel under **Settings → General → Proofing email**, and it
reaches the page encoded like the footer address, so it does not appear in the
HTML in plain text.

A subpage overrides `enabled` in either direction — useful to keep proofing off
across a public portfolio and switch it on for a single client handover:

```yaml
# gallery.yaml
subpages:
  - name: Wedding – Smith
    password: clientpass123
    proofing: true # or `false` to disable it on this subpage only
    albums:
      - ...
```

Precedence is **subpage → global**: a subpage's own `proofing:` wins, and an
album reached without a subpage follows `proofing.enabled`.

> [!NOTE]
> Photo essays are the exception. A published story is not an album handover,
> so an essay (`layout: essay`, `essayFile`, `essayText`) shows the proofing
> controls only when its subpage sets `proofing: true` **explicitly** — the
> global default does not reach into essays. Journal entries never show them.

## Client Proofing Links

The proofing above is anonymous: picks live in the visitor's browser and come
back to you as a link or an email, if they come back at all. A **client
proofing link** is the handover version. Create one per client in
**Admin → Proofing**:

- **Client** — a name for your overview and the greeting on the page.
- **Album** — any Immich album. It does not have to be in `gallery.yaml`; the
  link itself is what grants access to it.
- **Valid until** — optional. From the day after, the link shows "This link has
  expired" and every action on it is refused.
- **Downloads** — none, the client's selection as a ZIP, or the whole album as
  a ZIP, with an optional limit on how many ZIPs the link may start.

The client opens `https://your-site/proof/<token>` and hearts photos as usual.
Every change is **saved on the server** within a second, so they can stop and
come back later, from another device too. **Submit selection** locks it and
notifies you. Until then, you can watch the picks come in under
**Admin → Proofing**. **Reopen for changes** unlocks a submitted selection.

**Export.** Each link offers:

- **Copy file names (Lightroom)** — the selected file names without extension,
  comma-separated. Pasted into Lightroom's or Capture One's filename filter,
  `IMG_0412` finds the RAW as well as the JPEG the client saw.
- **CSV** — position in the album, file name and capture time.
- **TXT** — full file names, one per line.

**Notification.** Set `PROOFING_WEBHOOK_URL` and every first submit POSTs JSON
to it. The body carries `content` (Discord), `text` (Slack, Mattermost),
`title` and `message` (Gotify) and a structured `proofing` object (n8n, Home
Assistant, your own script), so most receivers work without an adapter. With
`SITE_URL` set, the message links straight to the selection in the admin panel.
A failing webhook never fails the client's submit.

```env
PROOFING_WEBHOOK_URL=https://discord.com/api/webhooks/…
```

**Security notes.**

- The token in the link is the only credential: 192 random bits, never shown
  in the admin panel's own URLs. Treat the link like a password; delete it in
  the admin panel to revoke it at once.
- Links are stored in `content/proofing.json` (mode `0600`), next to
  `analytics.json`, and are not part of the YAML backups.
- A site-wide password still applies: on a locked site, the client needs it
  too.
- Proofing pages are `noindex`, left out of the sitemap, and send no
  `Referer`.
- A subpage slugged `proof` would be hidden behind this route.

## Photo Zoom

Visitors can zoom into a photo in the lightbox to full resolution — one image
pixel per screen pixel, which is what judging sharpness takes. Off by default:
it hands out the full-resolution file, so it is switched on deliberately.

```yaml
# settings.yaml — the site-wide default
zoom: true
```

A subpage and an album can each override it, in either direction. The most
specific setting wins: **album → subpage → site**. An album's `zoom:` belongs to
the entry it is written on: an album listed on two pages can have zoom on one
and off on the other, and each page keeps its own choice. Listed twice on the
same page (in two sections), `false` wins.

```yaml
# gallery.yaml
subpages:
  - name: Clients
    zoom: true # every album on this page, unless it says otherwise
    albums:
      - 'album-uuid':
          zoom: false # not this one
```

In the admin panel the switch is under **Settings › General › Portfolio
Features**, and the page and album drawers in the page builder have an
_Inherit / On / Off_ choice.

**Using it.** A click on the photo zooms in by half (1.5× the fit size)
around the point clicked, and a second click goes back to fit. Double-tap on a
touch screen, or the magnifier button in the lightbox bar, zooms straight to
1:1 and back. Pinch, or Ctrl + scroll wheel / trackpad pinch, zooms
continuously between fit and 1:1 — never further, since enlarging past 1:1
only interpolates pixels and makes good focus look soft. Drag (or one finger)
pans; `+` / `-` step, `0` and `Esc` go back to fit (a second `Esc` closes the
viewer). Swiping to the next photo is off while zoomed, and changing photos
resets the zoom.

**What is shown.** The full-resolution file is requested only when a visitor
zooms — never on opening the viewer, and never for the neighbouring photos.
Until it arrives the preview is shown enlarged, with a small spinner on the
zoom button.

| Original                           | Zoom shows                                     |
| ---------------------------------- | ---------------------------------------------- |
| JPEG, AVIF                         | The original, with its location removed        |
| HEIC/HEIF, RAW/DNG, TIFF, JPEG XL… | Immich's full-size rendition, location removed |
| PNG, WebP, GIF                     | Not zoomable — their metadata is not scrubbed  |
| Edited in Immich (crop, rotate)    | Immich's edited full-size rendition            |
| Video                              | Not zoomable                                   |

Location is removed the same way as for [originals download](#originals-download):
GPS coordinates and place names below city level are overwritten in place;
camera data and colour profile stay. A file whose metadata cannot be read is
refused rather than sent.

Zoom into a JPEG or AVIF streams the original from Immich, so the API key
needs the `asset.download` permission (_Account Settings › API Keys_). With
only `asset.read` and `asset.view`, Immich answers `403` and the lightbox says
full resolution is unavailable; the Folio log shows
`Failed to stream … 403`. The same permission covers
[originals download](#originals-download).

Formats a browser cannot display need Immich's **full-size preview**
(_Administration › Settings › Image Settings › Full-size image_, JPEG format).
Immich generates it only while that setting is on, so turn it on and run the
_Generate Thumbnails_ job for existing photos. Without it, those photos show
the zoom button but answer "Full resolution is not available for this photo",
and the viewer stays on the preview. Immich does not say whether a rendition
exists until it is asked, so Folio cannot hide the button in advance.

AVIF originals tagged only with a BT.2020 colour tag (typical of Lightroom AVIF
exports) can look more saturated at 1:1 than in the preview: Immich's preview
ignores that tag and comes out desaturated (#827), while the browser shows the
original as tagged. The original is the accurate one.

A photo edited in Immich's own editor zooms into the edit, never into its
original: Immich keeps the edit apart from the file, so the original is the
unedited photo and whatever a crop removed would come back at 1:1. Immich has
a full-resolution rendition of every edit, whether or not full-size previews
are switched on, so edited photos do not depend on that setting.

On touch devices, photos above **50 megapixels** get no zoom control. Showing a
photo at 1:1 means decoding all of it — 200 MB of memory at 50 MP, 240 MB for a
60 MP frame — which phones and tablets do not reliably survive. With a mouse or
trackpad there is no limit.

Zoom is offered on album pages, including the album pages under a photo-essay
subpage (`/<page>/<album>`). The essay itself, journal entries and client
proofing links do not have it.

The zoom route re-checks the album allowlist, every password gate on a route to
the album, the zoom setting for that route, and that the photo is published and
belongs to the album. Answers are `Cache-Control: private` (browser only, one
hour, never a CDN), and each visitor can open 20 full-resolution files a minute.

**Bandwidth.** Every zoom sends a full-resolution file from Immich through
Folio to the visitor — commonly 5–25 MB per photo (a 60 MP JPEG is about
20 MB). At the rate limit of 20 a minute, one visitor can pull several hundred
megabytes a minute, and none of it is cached at a CDN. That is why zoom is off
by default; on a metered or slow uplink, switch it on only for the pages that
need it.

## Image Protection & Watermark

```yaml
protection:
  disableRightClick: true # suppress the context menu on images
  disableImageDrag: true # block drag-to-desktop

watermark:
  enabled: true
  text: '© Your Name'
  opacity: 0.5 # fraction, 0–1: 0.5 is 50%
  position: 'bottom-right' # bottom-right | bottom-left | center
```

`opacity` is a fraction between 0 and 1, the same unit the admin slider writes.
A value above 1 is read as a percentage (`90` means 0.9), so configs written
that way before the unit was fixed keep working.

> [!NOTE]
> Both are deterrents against casual copying, not protection. The image is in
> the browser, and anyone who wants it can take a screenshot. The watermark is
> an overlay on the lightbox, not burned into the file.

## SEO

```yaml
seo:
  title: 'My Portfolio | Photography'
  description: 'A curated selection of my best photography work.'
  titleTemplate: '%s | My Portfolio' # %s is the subpage or album title
  noIndex: false # true → ask search engines not to index the site
  noFollow: false # true → ask search engines not to follow links
```

`titleTemplate` shapes the browser and search-result title of every subpage and
album; the homepage uses `title` unchanged.

## Footer

Optional minimal footer with social links, in `settings.yaml`:

```yaml
footer:
  name: John Doe
  instagram: johndoe
  email: hello@example.com
  website: https://example.com
```

A `legal:` block with `enabled: true` adds an Impressum page at `/impressum` and
links it in the footer — see `content/settings.yaml.example` for every field.

Email, phone and `contactUrl` render as links. `contactUrl` is a second contact
channel such as a contact form, which case law accepts in place of a phone
number; it takes http(s) URLs only and is dropped with a warning otherwise.
`heading` replaces the "Angaben gemäß § 5 DDG" line, e.g. for § 5 ECG in Austria.

A privacy policy is written in the admin panel and stored in
`content/privacy.md`; `/privacy` shows it and the footer links it once the file
has text. `privacy: { enabled: false }` hides it without deleting the file. See
[Privacy Policy](admin-panel.md#privacy-policy).

A `contact:` block with `enabled: true` adds a contact form at `/contact` and
links it in the footer. Messages stay on the server (`content/messages/`) and
are read in the admin panel; see [Messages](admin-panel.md#messages). While the
Impressum has no `contactUrl`, it links this form as the second contact channel.

```yaml
contact:
  enabled: true
  notifyUrl: https://ntfy.sh/your-secret-topic # optional push for new messages
  retentionDays: 90 # delete messages after this many days
```

## About Page

Create `content/about.md` with YAML frontmatter:

```markdown
---
portrait: asset-uuid-for-your-portrait
name: Your Name
location: City, Country
gear:
  - Camera Body
  - Favorite Lens
---

Your bio text here. Supports full Markdown.
```

The page is served at `/about` and linked in the navigation. Turn it off in
`settings.yaml` without deleting the file:

```yaml
about:
  enabled: false
```

The admin panel's **Settings → About** section edits the same file — portrait,
name, location, gear list and bio — so `about.md` does not have to be written by
hand.

## Content Pages

Pages beyond the gallery — pricing and packages, workshops, press, a booking
FAQ — are content pages. Each one is a file, `content/pages/<slug>.md`, served
at `/<slug>`.

```markdown
---
title: 'Pricing'
description: 'Packages and rates for portrait and wedding sessions'
draft: true
---

## Portrait sessions

One hour on location, 25 edited photos.

![0a1b2c3d-…:wide](A session in the Highlands)
```

The frontmatter keys are `title`, `description` (used for search engines and
link previews), `password` and `draft`. The body uses the journal's block
syntax ([Journal & Photo Essays](journal.md)): headings, text and photo blocks
(`:wide` or `:fullbleed`). A page has no date, no reading time and no index,
and it has no map block.

### In the menu

A page appears in the header menu through a reference among the subpages in
`gallery.yaml`, at the position it should take:

```yaml
subpages:
  - name: Landscapes
    albums:
      - 'album-uuid-1'
  - page: pricing
```

A page without a reference is still reachable at `/<slug>`, but it is not in
the menu, which suits a page that is only shared by link. The menu stays flat:
a page cannot sit inside a subpage's sections. A reference to a page whose file
does not exist is skipped, and the config doctor reports it.

### Slugs

A page's slug must not be taken by a subpage, a standalone album, a journal
entry or one of the built-in routes (`about`, `map`, `journal`, `impressum`,
`privacy`, `install`, `admin`, `gate`, `api`, `proof`, `contact`). The admin
panel refuses to save a page on such a slug, and the doctor reports a collision
in a hand-edited file. Renaming a page's slug breaks old links: there are no
automatic redirects.

### Draft and password

A draft is visible only to a signed-in admin, and it is left out of the menu and
the sitemap. A `password` locks the page like a journal entry, with its own
cookie (`lb_auth_page_<slug>`). The site password, when one is set, applies
before either. Password-protected pages are not listed in the sitemap.

### In the admin panel

Admin → Pages lists pages next to the subpages, with a document icon and a
PAGE tag, and a separate "Not in menu" group for pages without a reference.
**+ New page** creates one (it starts blank and as a draft). Select a page to
edit its title, URL, draft flag, password and description, and to switch
"Show in menu"; dragging a page into or out of "Not in menu" does the same.
The menu change is saved with **Save Changes**, like any other change to the
structure. **Edit content →** opens the journal's block editor with a live
preview. Every save keeps a backup in `content/pages/.backups/`, and deleting a
page that is in the menu also removes its `gallery.yaml` reference; both files
are backed up first.

## Journal & Photo Essays

Long-form storytelling with fullbleed photos, side-by-side pairs, quotes and
captions lives in `content/journal/`, served at `/journal`. A subpage can also
be turned into a single photo essay.

→ **[Journal & Photo Essays](journal.md)**

## Finding UUIDs

- **Album UUIDs**: In Immich, go to Albums → click an album → the UUID is in the URL bar
- **Asset UUIDs**: Click any photo → the UUID is in the URL bar

## System & Security

Advanced system settings are configured via environment variables in your `.env` or `.env.local` file.

### Rate Limiting

To protect against brute-force attacks and resource exhaustion, Immich Folio includes an in-memory rate limiter. Each endpoint has its own bucket, so heavy image traffic cannot exhaust the budget for the password endpoints.

- `RATE_LIMIT_RPM`: requests per minute per IP for image, video, EXIF and health requests (default: `1500`).

The endpoints where a high limit would be the wrong default are fixed and not configurable:

| Endpoint               | Limit (req/min/IP) |
| ---------------------- | ------------------ |
| `POST /api/admin/auth` | 5                  |
| `POST /api/auth`       | 10                 |
| `/api/install`         | 10                 |
| `/api/zoom`            | 20                 |
| `/api/og`              | 30                 |
| `/api/install/albums`  | 30                 |
| `/api/webhook`         | 60                 |
| `/api/map`             | 120                |

> [!IMPORTANT]
> The limiter lives in the process memory of a single instance. It does not
> coordinate across replicas, and it starts empty after a restart.

### Trusted Proxies

If you run Immich Folio behind a reverse proxy (nginx, Traefik, Caddy, Cloudflare), tell it how many proxies sit in front. Without this, the rate limiter reads a client-supplied header and an attacker can pick their own bucket — defeating brute-force protection on the password endpoints.

- `TRUSTED_PROXY_HOPS`: Number of reverse proxies in front of the app (default: `0`).

```bash
# nginx / Traefik / Caddy directly in front of the app
TRUSTED_PROXY_HOPS=1

# Cloudflare in front of nginx
TRUSTED_PROXY_HOPS=2
```

The client IP is taken that many entries from the **right** of `X-Forwarded-For`. Proxies append the address they actually observed, so everything to the left is client-supplied and ignored — a visitor sending `X-Forwarded-For: 1.1.1.1` cannot influence which bucket they land in.

> ⚠️ **The app must be reachable only through the proxy.** Bind it to localhost (`127.0.0.1:3000`) or keep it on an internal Docker network. If clients can connect directly they control the entire header, and no setting can recover the real IP.

Matching nginx config:

```nginx
location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
```

`$proxy_add_x_forwarded_for` is the important one: it _appends_ the real peer address rather than overwriting the header.

#### Migrating from `TRUSTED_PROXIES`

`TRUSTED_PROXIES` has been removed. It matched proxy IPs against the socket peer address, which a self-hosted Next.js server never exposes — so the check never passed. Setting it silently put **every visitor into one shared rate-limit bucket**, letting a single client trip the limit for the entire site. If it is still set, the app assumes `TRUSTED_PROXY_HOPS=1` and logs a warning; replace it with an explicit value.

### Image Token Revocation

Asset tokens are deterministic — the same photo always yields the same token, which is what lets browsers cache images for a year. The image proxy validates the token but does not re-check album membership on every request.

Removing an album from `gallery.yaml` hides it from the site, but any image URL already handed out (bookmarked, embedded, cached by a browser) keeps working. To invalidate previously issued links, rotate `AUTH_SECRET` — this also signs out every password-protected gallery and admin session.