Koko210/immich-folio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

release: v0.13.0 (#535)

Browse Source 
Twenty-nine commits since v0.12.0. See CHANGELOG.md for the full list
and the upgrade notes.

Ten additions — the SEO package (site URL, robots.txt, sitemap.xml,
JSON-LD), slideshow mode, opt-in original downloads, copy-link,
previous/next album navigation, alt text from the Immich description,
per-album location precision, the update notice, a Help tab, and a
subpage cover grid separate from its photo grid. Two fixes: CJK album
slugs, and the lightbox control bar.

Photo of the Day (#476) was built on `dev` and reverted as not planned;
it never appears in a release.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01DmsHVRL9yQvckUB1ZpVWre

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Ralksta
2026-08-25 10:08:12 +02:00
committed by GitHub
parent 10ec68f493
commit a813433891
73 changed files with 4697 additions and 453 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
lib/config/index.ts
View File

@@ -2,10 +2,12 @@ import fs from 'node:fs';
import path from 'node:path';
import { env } from '../env';
import { resolveAuthSecret } from '../secret';
import { resolveSiteUrl } from '../siteUrl';
import { getInstallCredentials } from '../install';
import { loadYaml, clearYamlCache, validateUuid } from './parser';
import { resolveTheme, VALID_LAYOUTS, DEFAULT_PRESET } from './theme';
import { ALBUM_SORT_MODES, isAlbumSortMode, type AlbumSortMode } from '../albumSort';
import { LOCATION_PRECISIONS, isLocationPrecision, type LocationPrecision } from '../mapPrecision';
import {
slugify,
resolveExifDisplay,
@@ -56,27 +58,54 @@ export function getConfigOrNull(): AppConfig | null {
}
}
/** Converts raw YAML grid overrides into a typed partial GridConfig. */
export function buildSubpageGrid(raw?: {
interface RawGridOverrides {
columns?: number;
gap?: number;
aspectRatio?: string;
layout?: string;
}): { grid: Partial<GridConfig> } | Record<string, never> {
if (!raw) return {};
}
/** Converts raw YAML grid overrides into a typed partial GridConfig. */
function parseGridOverrides(raw: RawGridOverrides): Partial<GridConfig> {
return {
grid: {
...(raw.columns != null ? { columns: raw.columns } : {}),
...(raw.gap != null ? { gap: raw.gap } : {}),
...(raw.aspectRatio != null ? { aspectRatio: raw.aspectRatio } : {}),
...(raw.layout != null
? {
layout: (VALID_LAYOUTS.includes(raw.layout)
? raw.layout
: 'masonry') as GridConfig['layout'],
}
: {}),
},
...(raw.columns != null ? { columns: raw.columns } : {}),
...(raw.gap != null ? { gap: raw.gap } : {}),
...(raw.aspectRatio != null ? { aspectRatio: raw.aspectRatio } : {}),
...(raw.layout != null
? {
layout: (VALID_LAYOUTS.includes(raw.layout)
? raw.layout
: 'masonry') as GridConfig['layout'],
}
: {}),
};
}
/** Converts raw YAML grid overrides into a typed partial GridConfig. */
export function buildSubpageGrid(
raw?: RawGridOverrides,
): { grid: Partial<GridConfig> } | Record<string, never> {
if (!raw) return {};
return { grid: parseGridOverrides(raw) };
}
/**
* The two grids a subpage can override, as one spread-able object.
*
* `grid` sizes the photos inside its albums, `coverGrid` the album-cover tiles
* on the page itself. They were a single key until #523, where the admin field
* labelled "Album Cover Grid" turned out to retune every photo grid on the page
* as well. A gallery.yaml written before the split has no `coverGrid`, so the
* covers fall back to `grid` and such a page renders exactly as it did.
*/
function buildSubpageGrids(
grid?: RawGridOverrides,
coverGrid?: RawGridOverrides,
): { grid?: Partial<GridConfig>; coverGrid?: Partial<GridConfig> } {
const resolved = coverGrid ?? grid;
return {
...buildSubpageGrid(grid),
...(resolved ? { coverGrid: parseGridOverrides(resolved) } : {}),
};
}
@@ -139,6 +168,8 @@ export interface GalleryDerivation {
albumManualOrders: Record<string, string[]>;
albumGrids: Record<string, Partial<GridConfig>>;
albumCoverPositions: Record<string, string>;
albumDownloads: Record<string, boolean>;
albumLocationPrecision: Record<string, LocationPrecision>;
}
/**
@@ -162,18 +193,24 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
const albumManualOrders: Record<string, string[]> = {};
const albumGrids: Record<string, Partial<GridConfig>> = {};
const albumCoverPositions: Record<string, string> = {};
const albumDownloads: Record<string, boolean> = {};
const albumLocationPrecision: Record<string, LocationPrecision> = {};
/** Returns null for an entry whose album ID is not a UUID; callers drop it. */
function processAlbumEntry(
entry: string | Record<string, string | AlbumEntryObject>,
context: string,
inheritedLocation?: LocationPrecision,
): string | null {
if (typeof entry === 'string') {
if (inheritedLocation) albumLocationPrecision[entry] = inheritedLocation;
return validateUuid(entry, context);
}
const [uuid, value] = Object.entries(entry)[0];
const validatedUuid = validateUuid(uuid, context);
if (!validatedUuid) return null;
// The subpage's setting applies unless the album states its own below.
if (inheritedLocation) albumLocationPrecision[validatedUuid] = inheritedLocation;
if (typeof value === 'string') {
albumOverrides[validatedUuid] = value;
@@ -246,6 +283,13 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
}
albumCoverPositions[validatedUuid] = pos;
}
// Opt-in per album, never global: a public portfolio must not start
// handing out full-resolution originals because one client gallery
// needed to (#475).
if (value.download === true) albumDownloads[validatedUuid] = true;
const location = parseLocation(value.location, `${context}: album ${validatedUuid} location`);
if (location) albumLocationPrecision[validatedUuid] = location;
}
return validatedUuid;
}
@@ -254,12 +298,29 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
function processAlbumEntries(
entries: Array<string | Record<string, string | AlbumEntryObject>>,
context: string,
inheritedLocation?: LocationPrecision,
): string[] {
return entries
.map((entry) => processAlbumEntry(entry, context))
.map((entry) => processAlbumEntry(entry, context, inheritedLocation))
.filter((id): id is string => id !== null);
}
/**
* Narrow a raw `location:` value, or throw. Rejected rather than defaulted
* for the same reason as `sort`: a typo in a privacy setting that silently
* fell back to `exact` would publish the position it was meant to withhold.
*/
function parseLocation(raw: string | undefined, context: string): LocationPrecision | undefined {
if (raw == null) return undefined;
if (!isLocationPrecision(raw)) {
throw new Error(
`${context}: unknown location "${raw}". ` +
`Valid values are: ${LOCATION_PRECISIONS.join(', ')}.`,
);
}
return raw;
}
const standaloneAlbumIds = processAlbumEntries(gallery.albums ?? [], 'gallery.yaml albums');
let subpages: SubpageConfig[] = [];
@@ -279,19 +340,31 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
title: sec.title,
slug: slugify(sec.title),
description: sec.description,
albumIds: processAlbumEntries(sec.albums, `subpage "${sp.name}" section "${sec.title}"`),
albumIds: processAlbumEntries(
sec.albums,
`subpage "${sp.name}" section "${sec.title}"`,
parseLocation(sp.location, `subpage "${sp.name}" location`),
),
}));
// flat union of all section albums
albumIds = sections!.flatMap((sec) => sec.albumIds);
// Also include any top-level albums (outside sections)
const topLevel = processAlbumEntries(sp.albums ?? [], `subpage "${sp.name}"`);
const topLevel = processAlbumEntries(
sp.albums ?? [],
`subpage "${sp.name}"`,
parseLocation(sp.location, `subpage "${sp.name}" location`),
);
albumIds = [...topLevel, ...albumIds];
} else {
const albums = sp.albums ?? [];
if (albums.length === 0) {
throw new Error(`Subpage "${sp.name}" must have albums or sections`);
}
albumIds = processAlbumEntries(albums, `subpage "${sp.name}"`);
albumIds = processAlbumEntries(
albums,
`subpage "${sp.name}"`,
parseLocation(sp.location, `subpage "${sp.name}" location`),
);
}
return {
@@ -307,7 +380,7 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
essayText: sp.essayText,
enabled: sp.enabled !== false,
hidden: sp.hidden === true,
...buildSubpageGrid(sp.grid),
...buildSubpageGrids(sp.grid, sp.coverGrid),
};
});
} else if (gallery.subpages) {
@@ -327,14 +400,18 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
slug: slugify(name),
title: sp.title,
subtitle: sp.subtitle,
albumIds: processAlbumEntries(albumEntries, `subpage "${name}"`),
albumIds: processAlbumEntries(
albumEntries,
`subpage "${name}"`,
parseLocation(sp.location, `subpage "${name}" location`),
),
password: sp.password,
proofing: sp.proofing,
essayFile: sp.essayFile,
essayText: sp.essayText,
enabled: sp.enabled !== false,
hidden: sp.hidden === true,
...buildSubpageGrid(sp.grid),
...buildSubpageGrids(sp.grid, sp.coverGrid),
};
});
}
@@ -354,6 +431,8 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
albumManualOrders,
albumGrids,
albumCoverPositions,
albumDownloads,
albumLocationPrecision,
};
}
@@ -408,10 +487,13 @@ export function getConfig(): AppConfig {
title: 'Setup Required',
description: 'Please configure Immich Folio',
titleTemplate: '%s | Setup Required',
license: '',
noIndex: true,
noFollow: true,
},
heroImages: [],
siteUrl: null,
siteUrlSource: 'none',
colorMode: 'dark',
exifOnHover: true,
exif: resolveExifDisplay(),
@@ -434,6 +516,8 @@ export function getConfig(): AppConfig {
albumManualOrders: {},
albumGrids: {},
albumCoverPositions: {},
albumDownloads: {},
albumLocationPrecision: {},
navLinks: [],
cacheTtl: env.CACHE_TTL * 1000,
staleMaxAge: env.STALE_MAX_AGE * 1000,
@@ -460,6 +544,8 @@ export function getConfig(): AppConfig {
albumManualOrders,
albumGrids,
albumCoverPositions,
albumDownloads,
albumLocationPrecision,
} = deriveGallery(gallery);
const siteSeoTitle = settings.seo?.title || settings.title || env.SITE_TITLE || 'Gallery';
@@ -486,12 +572,17 @@ export function getConfig(): AppConfig {
titleTemplate: settings.seo?.titleTemplate || `%s | ${siteSeoTitle}`,
noIndex: settings.seo?.noIndex === true,
noFollow: settings.seo?.noFollow === true,
license: settings.seo?.license?.trim() || '',
},
heroImages: gallery.hero
? (Array.isArray(gallery.hero) ? gallery.hero : [gallery.hero])
.map((id) => validateUuid(id, 'gallery.yaml hero'))
.filter((id): id is string => id !== null)
: [],
...(() => {
const site = resolveSiteUrl(settings.url, env.SITE_URL);
return { siteUrl: site.url, siteUrlSource: site.source };
})(),
colorMode: resolveColorMode(settings.mode),
exifOnHover: settings.exifOnHover !== false,
exif: resolveExifDisplay(settings.exif, settings.exifOnHover),
@@ -547,6 +638,8 @@ export function getConfig(): AppConfig {
albumManualOrders,
albumGrids,
albumCoverPositions,
albumDownloads,
albumLocationPrecision,
navLinks: sanitizeNavLinks(settings.navLinks),
cacheTtl: env.CACHE_TTL * 1000,
staleMaxAge: env.STALE_MAX_AGE * 1000,

122
lib/config/schema.ts
View File

@@ -1,4 +1,5 @@
import type { AlbumSortMode } from '../albumSort';
import type { LocationPrecision } from '../mapPrecision';
export interface SubpageSectionConfig {
title: string;
@@ -15,7 +16,13 @@ export interface SubpageConfig {
albumIds: string[]; // flat list (all albums, incl. from sections)
sections?: SubpageSectionConfig[];
password?: string;
/** Photo grid for the albums on this page: global < subpage < album. */
grid?: Partial<GridConfig>;
/**
* The album-cover tiles on this page. Falls back to `grid` when unset, which
* is what a pre-#523 gallery.yaml renders with (#523).
*/
coverGrid?: Partial<GridConfig>;
proofing?: boolean;
essayFile?: string;
essayText?: string;
@@ -29,12 +36,16 @@ export interface SubpageObjectValue {
subtitle?: string;
password?: string;
grid?: Partial<GridConfig>;
/** Album-cover tiles only; falls back to `grid` when unset (#523). */
coverGrid?: Partial<GridConfig>;
proofing?: boolean;
essayFile?: string;
essayText?: string;
enabled?: boolean;
/** EXPERIMENTAL: reachable by direct link, but not shown in navigation */
hidden?: boolean;
/** Map precision for every album here that does not set its own (#469). */
location?: string;
// Both album lists reuse AlbumEntryObject rather than inlining the shape:
// the inline copies had already drifted (they never gained `heroImage`), and
// this path is live for map-style subpages.
@@ -91,6 +102,14 @@ export interface GridConfig {
'masonry' | 'uniform' | 'showcase' | 'filmstrip' | 'editorial-flow' | 'essay' | 'justified';
}
/**
* Bounds for the photo grid, shared by the site-wide and per-subpage inputs so
* the two forms cannot offer different ranges for the same setting.
*/
export const PHOTO_GRID_COLUMNS_MIN = 1;
export const PHOTO_GRID_COLUMNS_MAX = 6;
export const PHOTO_GRID_GAP_MAX = 48;
/**
* Bounds for the album-cover grid on a subpage. Shared with the admin inputs so
* the form and the renderer cannot drift apart.
@@ -105,12 +124,16 @@ export const COVER_GRID_TABLET_COLUMNS_MAX = 2;
/**
* The CSS custom properties that size the album-cover grid on a subpage.
*
* `columns` follows the same config as the photo grids (global `settings.yaml`
* < per-subpage override), so "3 columns" in the admin means three columns
* everywhere. `gap` deliberately does not: each theme preset picks the cover
* spacing as part of its look (1px monograph, 20px studio-modern), so the
* variable is only emitted when a subpage sets `gap` explicitly — otherwise the
* preset's own `--subpage-gap` stands.
* The overrides come from the subpage's own `coverGrid`, which sizes the cover
* tiles and nothing else — it used to be the same `grid` key the photos read,
* so a cover gap silently retuned every photo grid on the page (#523).
*
* `columns` still falls back to the global `settings.yaml` count, so a page
* that states nothing tiles its covers like its photos. `gap` deliberately does
* not: each theme preset picks the cover spacing as part of its look (1px
* monograph, 20px studio-modern), so the variable is only emitted when a
* subpage sets `gap` explicitly — otherwise the preset's own `--subpage-gap`
* stands.
*
* `--subpage-columns-tablet` is computed here rather than in CSS because
* `repeat()` does not reliably accept a `min()` expression.
@@ -158,7 +181,16 @@ export interface AppConfig {
titleTemplate: string;
noIndex: boolean;
noFollow: boolean;
/** Emitted as `license` in JSON-LD when set. */
license: string;
};
/**
* The site's own absolute URL, or null when nobody configured one. Sitemap,
* feed and JSON-LD need it and have no request context to derive it from.
*/
siteUrl: string | null;
/** Where `siteUrl` came from, so the admin panel can name it (#472). */
siteUrlSource: 'env' | 'settings' | 'none';
heroImages: string[];
/** Colour mode a first-time visitor lands on; their own choice overrides it. */
colorMode: ColorMode;
@@ -198,6 +230,10 @@ export interface AppConfig {
albumGrids: Record<string, Partial<GridConfig>>;
/** EXPERIMENTAL: per-album focal point for cover crops (CSS object-position). */
albumCoverPositions: Record<string, string>;
/** Albums whose originals may be downloaded. Absent means no (#475). */
albumDownloads: Record<string, boolean>;
/** Per-album map precision. Absent means `exact` (#469). */
albumLocationPrecision: Record<string, LocationPrecision>;
/** EXPERIMENTAL: external links appended to the header navigation. */
navLinks: NavLinkConfig[];
cacheTtl: number;
@@ -258,6 +294,14 @@ export interface AlbumEntryObject {
grid?: { columns?: number; gap?: number; aspectRatio?: string; layout?: string };
/** EXPERIMENTAL: focal point for the cover crop, e.g. "50% 25%" or "top" */
coverPosition?: string;
/** Offer the original file for download from the lightbox (#475). Off by default. */
download?: boolean;
/**
* How precisely this album's photographs may be placed on the map:
* `exact` (default), `city`, `country` or `hidden`. Narrowed to
* `LocationPrecision` in deriveGallery(), where a typo has to be rejected.
*/
location?: string;
}
export interface GalleryYaml {
@@ -281,18 +325,29 @@ export interface GalleryYaml {
essayText?: string;
enabled?: boolean;
hidden?: boolean;
/** Map precision inherited by every album here (#469). */
location?: string;
grid?: {
columns?: number;
gap?: number;
aspectRatio?: string;
layout?: string;
};
/** Album covers only; falls back to `grid` when unset (#523). */
coverGrid?: {
columns?: number;
gap?: number;
aspectRatio?: string;
layout?: string;
};
}>;
}
export interface SettingsYaml {
title?: string;
subtitle?: string;
/** Absolute site URL, e.g. https://folio.example. `SITE_URL` overrides it. */
url?: string;
lang?: string;
seo?: {
title?: string;
@@ -300,6 +355,8 @@ export interface SettingsYaml {
titleTemplate?: string;
noIndex?: boolean;
noFollow?: boolean;
/** Licence URL or identifier for structured data, e.g. a CC link (#472). */
license?: string;
};
/** 'dark' (default), 'light' or 'auto' — the visitor's starting colour mode. */
mode?: ColorMode;
@@ -450,11 +507,60 @@ export function resolveWatermarkOpacity(raw?: number): number {
return Math.min(1, Math.max(0, fraction));
}
/**
* URL slug for a display name.
*
* NFD + combining-mark removal folds Latin diacritics ("Café" -> "cafe"), but
* everything else keeps its letters: the separator class is \p{L}\p{N}, not
* [a-z0-9]. The ASCII-only version stripped CJK, Hangul and Cyrillic names down
* to an empty slug, which turned their links into "/" (#522). NFC at the end
* recomposes what NFD split — Hangul syllables decompose into jamo, and only
* the composed form matches what a browser sends back in the URL.
*
* Can still return '' for a name made purely of symbols or emoji; callers that
* need a routable slug must supply a fallback (see albumSlug).
*/
export function slugify(name: string): string {
return name
.toLowerCase()
.normalize('NFD')
.replace(/[\u0300-\u036f]/g, '')
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-+|-+$/g, '');
.replace(/[^\p{L}\p{N}]+/gu, '-')
.replace(/^-+|-+$/g, '')
.normalize('NFC');
}
/**
* Routable slug for an album. Falls back to the album id when the name has no
* letters or digits at all, so an emoji-only album is still reachable — and so
* two of them do not collide on the same empty slug.
*/
export function albumSlug(name: string, id: string): string {
return slugify(name) || id;
}
/**
* Normalize a slug that came in from a URL before comparing it to a stored one.
*
* Two things can differ even when the slug is "the same":
*
* - Percent-encoding. A non-ASCII path segment reaches the route handler
* still encoded ("%E5%AE%B6..."), so comparing it raw against the stored
* slug never matches — the half of #522 that survived fixing slugify().
* - Unicode form. Slugs are stored NFC; a non-Latin slug typed or pasted on
* macOS can arrive NFD, and the two are different strings that render the
* same.
*
* ASCII slugs are unaffected by either step. No stored slug can contain a '%',
* since slugify() drops it, so decoding cannot collide with a real slug.
*/
export function normalizeSlug(slug: string): string {
let decoded = slug;
try {
decoded = decodeURIComponent(slug);
} catch {
// Malformed percent sequence — compare what we were actually given rather
// than throwing a 500 on a hand-mangled URL.
}
return decoded.normalize('NFC');
}