From bbff86957a337e82c0333f5bff4a091a85037c04 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Thu, 8 Oct 2026 22:33:54 +1300 Subject: [PATCH] Update docs --- app/config.json | 28 +- docs/.vitepress/config.ts | 5 +- docs/.vitepress/configCheck.ts | 87 +++ docs/.vitepress/configSchema.ts | 155 +++-- .../theme/components/ConfigGenerator.vue | 641 ++++++++++++++++++ .../theme/components/configGenerator.data.ts | 100 +++ docs/.vitepress/theme/index.ts | 9 +- docs/README.md | 33 +- docs/config/gallery.md | 43 +- docs/config/generator.md | 12 + docs/config/index.md | 70 +- docs/config/ipp-options.md | 163 +++-- docs/config/lightbox.md | 12 +- docs/tests/configSchema.test.ts | 55 +- 14 files changed, 1196 insertions(+), 217 deletions(-) create mode 100644 docs/.vitepress/configCheck.ts create mode 100644 docs/.vitepress/theme/components/ConfigGenerator.vue create mode 100644 docs/.vitepress/theme/components/configGenerator.data.ts create mode 100644 docs/config/generator.md diff --git a/app/config.json b/app/config.json index cccb606..6d04d2a 100644 --- a/app/config.json +++ b/app/config.json @@ -1,17 +1,13 @@ { "ipp": { - "responseHeaders": { - "Cache-Control": "public, max-age=2592000", - "Access-Control-Allow-Origin": "*" - }, + "allowDownload": 0, "maxDownloadQuality": "original", + "downloadedFilename": 2, "maxZoomQuality": "preview", "motionPhotos": true, - "downloadedFilename": 2, - "allowDownload": 0, - "uploadUrl": "/upload", - "allowSlugLinks": true, "showHomePage": true, + "allowSlugLinks": true, + "uploadUrl": "/upload", "showMetadata": { "description": { "caption": false, @@ -39,26 +35,30 @@ "webLink": true } }, - "customInvalidResponse": false, "gallery": { - "singleImage": false, - "singleVideo": true, - "singleItemAutoOpen": true, "showTitle": true, "showDescription": false, "showExpiryDate": false, "expiryDateFormat": "YYYY-MM-DD", "expiryDateLocale": "", - "groupByDate": false, "showDownloadZip": true, + "groupByDate": false, + "singleImage": false, + "singleVideo": true, + "singleItemAutoOpen": true, "cacheTime": 300 }, "lightbox": { "showArrows": true, - "showDownload": true, "mobileArrows": false, + "showDownload": true, "autoPlayVideos": false, "options": {} + }, + "customInvalidResponse": false, + "responseHeaders": { + "Cache-Control": "public, max-age=2592000", + "Access-Control-Allow-Origin": "*" } } } diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 91321f1..48c6c22 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,5 +1,5 @@ import { defineConfigWithTheme, type DefaultTheme } from 'vitepress' -import { configSchemaPlugin } from './configSchema' +import { configCheckPlugin } from './configCheck' const REPO_URL = 'https://github.com/alangrainger/immich-public-proxy' @@ -46,7 +46,7 @@ export default async () => defineConfigWithTheme({ ], vite: { // Fails the build when the config reference pages and the default config files disagree - plugins: [configSchemaPlugin()] + plugins: [configCheckPlugin()] }, themeConfig: { logo: '/ipp.svg', @@ -82,6 +82,7 @@ export default async () => defineConfigWithTheme({ text: 'Configuration', items: [ { text: 'Overview', link: '/config/' }, + { text: 'Config generator', link: '/config/generator' }, { text: 'Environment variables', link: '/config/environment-variables' }, { text: 'General options', link: '/config/ipp-options' }, { text: 'Gallery', link: '/config/gallery' }, diff --git a/docs/.vitepress/configCheck.ts b/docs/.vitepress/configCheck.ts new file mode 100644 index 0000000..6a6ecc6 --- /dev/null +++ b/docs/.vitepress/configCheck.ts @@ -0,0 +1,87 @@ +import { readdirSync, readFileSync } from 'node:fs' +import { basename, join, resolve } from 'node:path' +import { fileURLToPath } from 'node:url' +import type { Plugin } from 'vite' +import { checkKeys, LABELS, parsePage, parseRenamedKeys, type ConfigKey, type RenamedKey } from './configSchema' + +/* + The Node half of the config schema: reads the reference pages and the + default config files from disk, and fails the docs build when they + disagree. The parsing and the checks themselves are in configSchema.ts. +*/ + +const DOCS_CONFIG_DIR = fileURLToPath(new URL('../config/', import.meta.url)) +const REPO_ROOT = fileURLToPath(new URL('../../', import.meta.url)) +/** The default config files, as repo paths. Both containers can share one config, so they are checked as one. */ +const DEFAULTS_FILES = ['app/config.json', 'upload-app/config.json'] + +/** + * Read every page in docs/config and both default config files, and check + * them against each other. Returns `checkKeys`' keys, the renamed keys from + * config/upgrading.md, and every problem, the pages' own format problems + * first. A renamed key whose current name no page documents is a problem too, + * and so is a label in `LABELS` for a key no page documents. + */ +export function readConfigSchema (): { keys: ConfigKey[], renamed: RenamedKey[], problems: string[] } { + const keys: ConfigKey[] = [] + const problems: string[] = [] + for (const file of readdirSync(DOCS_CONFIG_DIR).filter(name => name.endsWith('.md')).sort()) { + const page = parsePage(readFileSync(join(DOCS_CONFIG_DIR, file), 'utf8'), '/config/' + basename(file, '.md')) + keys.push(...page.keys) + problems.push(...page.problems) + } + const files = DEFAULTS_FILES.map(name => ({ name, config: JSON.parse(readFileSync(join(REPO_ROOT, name), 'utf8')) })) + const checked = checkKeys(keys, files) + problems.push(...checked.problems) + + const renamed = parseRenamedKeys(readFileSync(join(DOCS_CONFIG_DIR, 'upgrading.md'), 'utf8')) + const documented = new Set(checked.keys.map(key => key.path)) + for (const { from, to } of renamed) { + if (!documented.has(to)) problems.push(`docs/config/upgrading.md: \`${from}\` is renamed to \`${to}\`, which no page documents`) + } + for (const path of Object.keys(LABELS)) { + if (!documented.has(path)) problems.push(`docs/.vitepress/configSchema.ts: LABELS has a label for \`${path}\`, which no page documents`) + } + return { keys: checked.keys, renamed, problems } +} + +/** The check's problems as one message, or undefined when there are none. */ +function problemsMessage (): string | undefined { + const { problems } = readConfigSchema() + if (problems.length === 0) return undefined + return 'The config reference pages (docs/config) and the default config files disagree. ' + + 'See "Config reference pages" in docs/README.md.\n' + problems.map(problem => ' - ' + problem).join('\n') +} + +/** + * Fails `vitepress build` when the config reference pages and the default + * config files disagree, so a mismatch never deploys. `vitepress dev` only + * warns, at start and again when a page or a default config file changes, so + * a half-edited page doesn't stop the server. + */ +export function configCheckPlugin (): Plugin { + const repoFiles = DEFAULTS_FILES.map(name => join(REPO_ROOT, name)) + const isChecked = (file: string) => + repoFiles.includes(resolve(file)) || (resolve(file).startsWith(DOCS_CONFIG_DIR) && file.endsWith('.md')) + let isBuild = false + return { + name: 'ipp-config-check', + configResolved (config) { + isBuild = config.command === 'build' + }, + buildStart () { + const message = problemsMessage() + if (message && isBuild) this.error(message) + else if (message) this.warn(message) + }, + configureServer (server) { + // Outside the docs folder, so Vite doesn't watch them unless told to + server.watcher.add(repoFiles) + }, + handleHotUpdate ({ file, server }) { + if (!isChecked(file)) return + const message = problemsMessage() + if (message) server.config.logger.warn(message) + } + } +} diff --git a/docs/.vitepress/configSchema.ts b/docs/.vitepress/configSchema.ts index dfabfc4..36b61fb 100644 --- a/docs/.vitepress/configSchema.ts +++ b/docs/.vitepress/configSchema.ts @@ -1,21 +1,27 @@ -import { readdirSync, readFileSync } from 'node:fs' -import { basename, join } from 'node:path' -import { fileURLToPath } from 'node:url' -import { isDeepStrictEqual } from 'node:util' -import type { Plugin } from 'vite' - /* - Reads the config reference pages (docs/config/*.md) into a schema and checks - them against the default config files, both ways. The page format this - parser accepts is the contract in docs/README.md, "Config reference pages"; - change the two together. + Parses the config reference pages (docs/config/*.md) into a schema and + checks it against the default config files, both ways. The page format + this parser accepts is the contract in docs/README.md, "Config reference + pages"; change the two together. + + No Node APIs here: the config generator runs these checks in the browser + too. Reading the files from disk is in configCheck.ts. */ -/** Whether a config.json value is a plain JSON object (not an array or null). */ -function isObject (value: unknown): value is Record { +/** Whether a config value is a plain JSON object (not an array or null). */ +export function isObject (value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value) } +/** Deep equality of two JSON values; the order of object keys doesn't matter. */ +export function sameValue (a: unknown, b: unknown): boolean { + if (a === b) return true + if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((item, i) => sameValue(item, b[i])) + if (!isObject(a) || !isObject(b)) return false + const keys = Object.keys(a) + return keys.length === Object.keys(b).length && keys.every(key => Object.hasOwn(b, key) && sameValue(a[key], b[key])) +} + /** The types a `**Type:**` line can name, each with the check its default must pass. */ const TYPE_CHECKS = { bool: (value: unknown) => typeof value === 'boolean', @@ -28,6 +34,47 @@ const TYPE_CHECKS = { export type ConfigType = keyof typeof TYPE_CHECKS +/** Whether a value is of a documented type, e.g. `matchesType('int', 2)`. */ +export function matchesType (type: ConfigType, value: unknown): boolean { + return TYPE_CHECKS[type](value) +} + +/** Words a label writes in capitals. Add an acronym here when a new key name contains one. */ +const ACRONYMS = new Set(['exif', 'gps', 'iso', 'url']) + +/** + * Labels for the keys whose name, split into words, doesn't read well or + * leaves out a unit. The check fails on a path that no page documents, so a + * renamed key can't leave its label behind. + */ +export const LABELS: Record = { + 'ipp.gallery.singleImage': 'Gallery page for a single image', + 'ipp.gallery.singleVideo': 'Gallery page for a single video', + 'ipp.gallery.singleItemAutoOpen': 'Open single items in the lightbox', + 'ipp.gallery.cacheTime': 'Cache time (seconds)', + 'ipp.lightbox.autoPlayVideos': 'Autoplay videos', + 'ipp.showMetadata.exif.dateTimeOriginal': 'Date taken', + 'ipp.showMetadata.exif.fNumber': 'Aperture', + 'ipp.showMetadata.location.webLink': 'Map link', + 'ipp.upload.maxFileSize': 'Max file size (MB)', + 'ipp.upload.rateLimit': 'Rate limit (files per minute)', + 'ipp.upload.byteBudget': 'Byte budget (MB per hour)', + 'ipp.upload.notifyTimeout': 'Notify timeout (ms)' +} + +/** + * A key's label for the config generator: its entry in `LABELS`, or else the + * last part of its path as words, so `showArrows` is "Show arrows" and + * `notifyUrl` is "Notify URL". + */ +export function keyLabel (path: string): string { + if (Object.hasOwn(LABELS, path)) return LABELS[path] + const name = path.slice(path.lastIndexOf('.') + 1) + const words = name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(' ') + const text = words.map(word => ACRONYMS.has(word) ? word.toUpperCase() : word).join(' ') + return text.charAt(0).toUpperCase() + text.slice(1) +} + /** One allowed value of a key, from its enum list. */ export interface ConfigValue { value: unknown @@ -50,6 +97,8 @@ export interface ConfigKey { page: string /** The anchor of the key's section on that page. */ anchor: string + /** For a row of a flag table, the heading of the table's section. */ + group?: string } /** A default config file, named by its repo path for messages. */ @@ -208,7 +257,7 @@ export function parsePage (markdown: string, page: string): { keys: ConfigKey[], const parsed = parseLiteral(row[columns.default].replace(/`/g, '')) if (!isConfigType(type)) problems.push(`${where}: \`${path}\` has an unknown type: ${row[columns.type]}`) else if (!parsed.ok) problems.push(`${where}: the default of \`${path}\` is not JSON: ${row[columns.default]}`) - else keys.push({ path, type, default: parsed.value, description: row[columns.description], page, anchor }) + else keys.push({ path, type, default: parsed.value, description: row[columns.description], page, anchor, group: heading.text }) } } } @@ -231,9 +280,10 @@ function flatten (config: Record, prefix = ''): Map file.name).join(' nor ')}`) continue } - if (!TYPE_CHECKS[key.type](node.value)) { + if (!matchesType(key.type, node.value)) { problems.push(`\`${key.path}\` is documented as \`${key.type}\` in ${where(key)} but is ${json(node.value)} in ${node.file}`) continue } if (isGroup(key)) continue if (key.default === undefined) { if (!isFreeForm(key)) problems.push(`\`${key.path}\` has no default in ${where(key)}`) - } else if (!isDeepStrictEqual(key.default, node.value)) { + } else if (!sameValue(key.default, node.value)) { problems.push(`\`${key.path}\` defaults to ${json(key.default)} in ${where(key)} but to ${json(node.value)} in ${node.file}`) } - if (key.values && !key.values.some(allowed => isDeepStrictEqual(allowed.value, node.value))) { + if (key.values && !key.values.some(allowed => sameValue(allowed.value, node.value))) { problems.push(`the allowed values of \`${key.path}\` in ${where(key)} do not include its default, ${json(node.value)}`) } for (const allowed of key.values ?? []) { - if (!TYPE_CHECKS[key.type](allowed.value)) { + if (!matchesType(key.type, allowed.value)) { problems.push(`the allowed value ${json(allowed.value)} of \`${key.path}\` in ${where(key)} is not a \`${key.type}\``) } } @@ -304,51 +354,38 @@ export function checkKeys (keys: ConfigKey[], files: DefaultsFile[]): { keys: Co const isLeaf = !isObject(node.value) || Object.keys(node.value).length === 0 if (isLeaf && !covered(path)) problems.push(`\`${path}\` in ${node.file} is not documented on any page in docs/config`) } + const order = [...nodes.keys()] + fields.sort((a, b) => order.indexOf(a.path) - order.indexOf(b.path)) return { keys: fields, problems } } -const DOCS_CONFIG_DIR = fileURLToPath(new URL('../config/', import.meta.url)) -const REPO_ROOT = fileURLToPath(new URL('../../', import.meta.url)) -/** The default config files, as repo paths. Both containers can share one config, so they are checked as one. */ -const DEFAULTS_FILES = ['app/config.json', 'upload-app/config.json'] - -/** - * Read every page in docs/config and both default config files, and check - * them against each other. Returns `checkKeys`' keys and problems, with the - * pages' own format problems first. - */ -export function readConfigSchema (): { keys: ConfigKey[], problems: string[] } { - const keys: ConfigKey[] = [] - const problems: string[] = [] - for (const file of readdirSync(DOCS_CONFIG_DIR).filter(name => name.endsWith('.md')).sort()) { - const page = parsePage(readFileSync(join(DOCS_CONFIG_DIR, file), 'utf8'), '/config/' + basename(file, '.md')) - keys.push(...page.keys) - problems.push(...page.problems) - } - const files = DEFAULTS_FILES.map(name => ({ name, config: JSON.parse(readFileSync(join(REPO_ROOT, name), 'utf8')) })) - const checked = checkKeys(keys, files) - return { keys: checked.keys, problems: [...problems, ...checked.problems] } +/** One row of the tables on Renamed config keys. */ +export interface RenamedKey { + /** The old dotted path. */ + from: string + /** The current dotted path. */ + to: string + /** The Current key cell as markdown, which can say how the values changed. */ + note: string } /** - * Fails `vitepress build` when the config reference pages and the default - * config files disagree, so a mismatch never deploys. `vitepress dev` only - * warns, so a half-edited page doesn't stop the server. + * Read the renamed keys from config/upgrading.md: every table with `Old key` + * and `Current key` columns, taking the first inline-code path in each cell. */ -export function configSchemaPlugin (): Plugin { - let isBuild = false - return { - name: 'ipp-config-schema', - configResolved (config) { - isBuild = config.command === 'build' - }, - buildStart () { - const { problems } = readConfigSchema() - if (problems.length === 0) return - const message = 'The config reference pages (docs/config) and the default config files disagree. ' + - 'See "Config reference pages" in docs/README.md.\n' + problems.map(problem => ' - ' + problem).join('\n') - if (isBuild) this.error(message) - else this.warn(message) +export function parseRenamedKeys (markdown: string): RenamedKey[] { + const renamed: RenamedKey[] = [] + for (const block of toBlocks(markdown)) { + if (block.kind !== 'table') continue + const [header, ...rows] = block.rows + const from = header.indexOf('Old key') + const to = header.indexOf('Current key') + if (from === -1 || to === -1) continue + for (const row of rows) { + const oldPath = /`([^`]+)`/.exec(row[from])?.[1] + const newPath = /`([^`]+)`/.exec(row[to])?.[1] + if (oldPath && newPath) renamed.push({ from: oldPath, to: newPath, note: row[to] }) } } + return renamed } diff --git a/docs/.vitepress/theme/components/ConfigGenerator.vue b/docs/.vitepress/theme/components/ConfigGenerator.vue new file mode 100644 index 0000000..59608dd --- /dev/null +++ b/docs/.vitepress/theme/components/ConfigGenerator.vue @@ -0,0 +1,641 @@ + + + + +