immich-folio/content/gallery.yaml.example

# ── Gallery Structure ──────────────────────────────────────────────
# This file defines WHICH albums and subpages are shown.
# Global settings (theme, map, legal, title) now live in content/settings.yaml.

# Hero images for the homepage carousel (Immich asset UUIDs)
hero:
  - "your-asset-uuid-1"
  - "your-asset-uuid-2"

# Standalone albums (shown on the home page)
#
# Photo order inside an album: by default a Folio album mirrors the Immich
# timeline. The optional `sort` key lets the portfolio order differ from the
# archive order, without changing anything in Immich.
#
#   immich    Default. Inherits the album's own asc/desc setting in Immich.
#             This is capture-time order — Immich does not expose the drag
#             order from its web UI, so Folio cannot reproduce that.
#   newest    Capture time, newest first, whatever Immich is set to.
#   oldest    Capture time, oldest first.
#   filename  originalFileName, natural order (IMG_2 before IMG_10).
#             Matches scanned-film and camera-export workflows.
#   manual    Pinned photos first, in the order given by `assetOrder`;
#             everything else follows in the album's Immich order. Far easier
#             to set in /admin, which has a drag & drop editor for it.
#
# Two things 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.
#   • Lightbox permalinks (#photo-3) are positional, so changing an album's
#     sort moves where a previously shared link lands.
#
# `sort` works the same on subpage and section albums, shown further down.
albums:
  - "your-album-uuid-1" # no sort key → Immich order, exactly as before
  - "your-album-uuid-2":
      sort: filename # an entry may carry only a sort, with no title override
  - "your-album-uuid-3":
      title: "Hokkaido, in sequence"
      sort: manual
      assetOrder: # pinned, in this order. Everything else follows automatically.
        - "asset-uuid-opening-frame"
        - "asset-uuid-second-frame"

# Subpages: group albums under custom URL paths
subpages:
  "Travel":
    - "album-uuid-3"
    - "album-uuid-4"
  "Projects":
    title: "My Creative Projects" # Optional: Header title, defaults to Navigation key ("Projects")
    subtitle: "A collection of 2026 highlights in 35mm film." # Optional: Sub-text for headers
    password: "your-password" # Optional protection
    # hidden: true # EXPERIMENTAL: reachable by direct link, but not shown in navigation
    albums:
      - "album-uuid-5"
      - "album-uuid-6":
          title: "Private Project #7"
          description: "Shot on 35mm film in Vienna, spring 2025." # Optional: shown below album title
          password: "scrypt:..." # Recommended: secure hash (generated via logs)
          # grid: # EXPERIMENTAL: per-album grid override (wins over page/global grid)
          #   layout: "justified"
          #   columns: 2
          # coverPosition: "50% 25%" # EXPERIMENTAL: focal point for the cover crop ("top", "center bottom", "50% 25%")

# ── Subpage with Sections ──────────────────────────────────────────
# Use sections to group albums by location, theme, or any other logic.
# A typographic table of contents is rendered above the albums.
# Sections are optional: leave them out and you get a flat album grid (as above).
subpages:
  - name: Japan
    title: Japan
    subtitle: "Reisen durch ein Land voller Kontraste."

    sections:
      - title: Tokyo
        description: "Megacity, Neonlichter, Stille im Lärm."
        albums:
          - "album-uuid-tokyo-1"               # Uses Immich album name
          - "album-uuid-tokyo-2": Shinjuku bei Nacht  # Custom title override
          - "album-uuid-tokyo-3"

      - title: Kyoto
        description: "Tempel, Bambuswälder, goldener Herbst."
        albums:
          - "album-uuid-kyoto-1": Fushimi Inari
          - "album-uuid-kyoto-2"

      - title: Osaka
        albums:                                # description is optional
          - "album-uuid-osaka-1"
          - "album-uuid-osaka-2"

  # ── Photo Essay / Storytelling Subpage Example ───────────────────
  # Render editorial Markdown essays with fullbleed & side-by-side images.
  #
  # essayFile is a SLUG, not a path: "sample-story" resolves to
  # content/journal/sample-story.md (or content/essays/sample-story.md).
  # Slashes and dots are rejected. Copy the shipped template to get started:
  #   cp content/journal/sample-story.md.example content/journal/sample-story.md
  #
  # Leave essayFile out and keep `layout: essay`, and the essay is generated
  # from the albums below — one heading per album, followed by its photos.
  # See docs/journal.md for the Markdown block syntax.
  - name: Highlands
    title: "Icelandic Highlands"
    subtitle: "A Photo Essay"
    essayFile: "sample-story"
    grid:
      layout: essay
    albums:
      - "album-uuid-iceland-1"