@stati/core 1.27.2 → 1.29.0

package/dist/core/expand.d.ts

@@ -0,0 +1,86 @@
+import type { FrontMatter, Logger, PageModel, PaginationData, StatiConfig } from '../types/index.js';
+/** URL segment before the page number when `paginate.path` is not set */
+export declare const DEFAULT_PAGINATION_PATH = "page";
+/**
+ * Resolved pagination settings.
+ */
+interface PaginationSettings {
+    size: number;
+    path: string;
+}
+/**
+ * Returns the parameter name of a `[param].md` template, or undefined for other pages.
+ *
+ * @param page - A loaded page
+ * @returns The name between the brackets
+ */
+export declare function getTemplateParam(page: PageModel): string | undefined;
+/**
+ * Replaces `{param}` with the label in a string. `{{param}}` produces the literal `{param}`,
+ * and placeholders of other names are left as they are.
+ *
+ * @param text - The string to fill in
+ * @param param - The template's parameter name, such as `tag`
+ * @param label - The value, such as `CSS`
+ * @returns The string with its placeholders replaced
+ *
+ * @example
+ * ```typescript
+ * replacePlaceholders('Posts tagged {tag}', 'tag', 'CSS'); // 'Posts tagged CSS'
+ * replacePlaceholders('Use {{tag}} in titles', 'tag', 'CSS'); // 'Use {tag} in titles'
+ * replacePlaceholders('{author} on {tag}', 'tag', 'CSS'); // '{author} on CSS'
+ * ```
+ */
+export declare function replacePlaceholders(text: string, param: string, label: string): string;
+/**
+ * Copies a template's front matter for one generated page, with `{param}` placeholders filled
+ * in. `generate` and `permalink` are copied as they are: they configure the template, and
+ * `permalink` takes the key through `[param]` instead.
+ *
+ * @param frontMatter - The template's front matter
+ * @param param - The template's parameter name
+ * @param label - The value for the page
+ * @returns The page's front matter
+ */
+export declare function substituteFrontMatter(frontMatter: FrontMatter, param: string, label: string): FrontMatter;
+/**
+ * URL of page `pageNumber` of a listing whose first page is `baseUrl`. Later pages follow the
+ * first page's trailing-slash style: `/blog` → `/blog/page/2`, `/blog/` → `/blog/page/2/`,
+ * `/` → `/page/2`.
+ *
+ * @param baseUrl - URL of the first page
+ * @param path - URL segment before the page number
+ * @param pageNumber - Page number, starting at 1
+ * @returns The page URL
+ */
+export declare function getPaginationUrl(baseUrl: string, path: string, pageNumber: number): string;
+/**
+ * Builds the pagination data of every page of a listing.
+ *
+ * @param baseUrl - URL of the first page
+ * @param items - Everything the listing shows, in order
+ * @param settings - Page size and URL segment
+ * @returns One entry per page; there is always at least one
+ */
+export declare function paginateItems(baseUrl: string, items: readonly PageModel[], settings: PaginationSettings): PaginationData[];
+/**
+ * Turns the pages loaded from Markdown into the pages of a build:
+ *
+ * - Each `[param].md` template is removed and replaced by one page per key: per value of
+ *   `generate.from` in its collection, and per `collections.generate` entry that names it.
+ *   A template that produces no keys produces no output.
+ * - Every page with `paginate`, and every generated page whose template has
+ *   `generate.paginate`, gets one more page per additional slice of its items.
+ *
+ * Generated and pagination pages are virtual: they are never collection members and are left
+ * out of navigation, search and RSS unless they opt in. A virtual page whose URL or output
+ * file is already taken is skipped with a warning.
+ *
+ * @param loaded - Pages loaded from Markdown files
+ * @param config - Stati configuration
+ * @param logger - Logger for warnings
+ * @returns The pages to build: loaded pages without templates, then virtual pages
+ */
+export declare function expandPages(loaded: PageModel[], config: StatiConfig, logger: Logger): Promise<PageModel[]>;
+export {};
+//# sourceMappingURL=expand.d.ts.map

package/dist/core/expand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand.d.ts","sourceRoot":"","sources":["../../src/core/expand.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EAGX,MAAM,EACN,SAAS,EACT,cAAc,EACd,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAmB3B,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,SAAS,CAAC;AAE9C;;GAEG;AACH,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAWD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtF;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,WAAW,CASb;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAU1F;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,QAAQ,EAAE,kBAAkB,GAC3B,cAAc,EAAE,CAclB;AA6FD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,SAAS,EAAE,EACnB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,EAAE,CAAC,CA+NtB"}

package/dist/core/expand.js

@@ -0,0 +1,484 @@
+import { basename, join, relative, sep } from 'node:path';
+import { getPageOutputFile, resolveSrcDir, slugify } from './utils/index.js';
+import { findCollectionPath, getCollections, resolveCollectionPath } from './collections.js';
+/**
+ * File name of a template that expands into one page per key, such as `[tag].md`.
+ */
+const TEMPLATE_FILE_PATTERN = /^\[([^\]]*)\]\.md$/;
+/**
+ * Valid template parameter names: `[tag].md`, `[author].md`, `[release_year].md`.
+ */
+const PARAM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/**
+ * Valid `paginate.path` values: one URL segment.
+ */
+const PAGINATION_PATH_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/** URL segment before the page number when `paginate.path` is not set */
+export const DEFAULT_PAGINATION_PATH = 'page';
+/**
+ * Returns the parameter name of a `[param].md` template, or undefined for other pages.
+ *
+ * @param page - A loaded page
+ * @returns The name between the brackets
+ */
+export function getTemplateParam(page) {
+    return TEMPLATE_FILE_PATTERN.exec(basename(page.sourcePath))?.[1];
+}
+/**
+ * Replaces `{param}` with the label in a string. `{{param}}` produces the literal `{param}`,
+ * and placeholders of other names are left as they are.
+ *
+ * @param text - The string to fill in
+ * @param param - The template's parameter name, such as `tag`
+ * @param label - The value, such as `CSS`
+ * @returns The string with its placeholders replaced
+ *
+ * @example
+ * ```typescript
+ * replacePlaceholders('Posts tagged {tag}', 'tag', 'CSS'); // 'Posts tagged CSS'
+ * replacePlaceholders('Use {{tag}} in titles', 'tag', 'CSS'); // 'Use {tag} in titles'
+ * replacePlaceholders('{author} on {tag}', 'tag', 'CSS'); // '{author} on CSS'
+ * ```
+ */
+export function replacePlaceholders(text, param, label) {
+    const name = param.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&');
+    return text.replace(new RegExp(`\\{\\{${name}\\}\\}|\\{${name}\\}`, 'g'), (match) => match.startsWith('{{') ? `{${param}}` : label);
+}
+/**
+ * Deep-copies a value from front matter (YAML data: strings, numbers, booleans, dates, lists
+ * and mappings), passing every string inside it through `mapString`.
+ */
+function copyValue(value, mapString = (text) => text) {
+    if (typeof value === 'string') {
+        return mapString(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => copyValue(item, mapString));
+    }
+    if (value instanceof Date) {
+        return new Date(value.getTime());
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, copyValue(item, mapString)]));
+    }
+    return value;
+}
+/**
+ * Copies a template's front matter for one generated page, with `{param}` placeholders filled
+ * in. `generate` and `permalink` are copied as they are: they configure the template, and
+ * `permalink` takes the key through `[param]` instead.
+ *
+ * @param frontMatter - The template's front matter
+ * @param param - The template's parameter name
+ * @param label - The value for the page
+ * @returns The page's front matter
+ */
+export function substituteFrontMatter(frontMatter, param, label) {
+    const result = {};
+    for (const [key, value] of Object.entries(frontMatter)) {
+        result[key] =
+            key === 'generate' || key === 'permalink'
+                ? copyValue(value)
+                : copyValue(value, (text) => replacePlaceholders(text, param, label));
+    }
+    return result;
+}
+/**
+ * URL of page `pageNumber` of a listing whose first page is `baseUrl`. Later pages follow the
+ * first page's trailing-slash style: `/blog` → `/blog/page/2`, `/blog/` → `/blog/page/2/`,
+ * `/` → `/page/2`.
+ *
+ * @param baseUrl - URL of the first page
+ * @param path - URL segment before the page number
+ * @param pageNumber - Page number, starting at 1
+ * @returns The page URL
+ */
+export function getPaginationUrl(baseUrl, path, pageNumber) {
+    if (pageNumber <= 1) {
+        return baseUrl;
+    }
+    if (baseUrl === '/') {
+        return `/${path}/${pageNumber}`;
+    }
+    return baseUrl.endsWith('/')
+        ? `${baseUrl}${path}/${pageNumber}/`
+        : `${baseUrl}/${path}/${pageNumber}`;
+}
+/**
+ * Builds the pagination data of every page of a listing.
+ *
+ * @param baseUrl - URL of the first page
+ * @param items - Everything the listing shows, in order
+ * @param settings - Page size and URL segment
+ * @returns One entry per page; there is always at least one
+ */
+export function paginateItems(baseUrl, items, settings) {
+    const totalPages = Math.max(1, Math.ceil(items.length / settings.size));
+    const urls = Array.from({ length: totalPages }, (_, i) => getPaginationUrl(baseUrl, settings.path, i + 1));
+    return urls.map((_, i) => ({
+        pageNumber: i + 1,
+        totalPages,
+        items: items.slice(i * settings.size, (i + 1) * settings.size),
+        ...(i > 0 && { prevUrl: urls[i - 1] }),
+        ...(i < totalPages - 1 && { nextUrl: urls[i + 1] }),
+        // One array for the whole listing, not one per page; templates get their own copy
+        urls,
+    }));
+}
+/**
+ * Reads `paginate` settings from front matter.
+ *
+ * @param value - `paginate` or `generate.paginate`: a size, or `{ size, path }`
+ * @param warn - Reports an invalid value
+ * @returns The settings, or undefined when the value is absent or invalid
+ */
+function parsePaginate(value, warn) {
+    if (value === undefined || value === null || value === false) {
+        return undefined;
+    }
+    const options = typeof value === 'number' ? { size: value } : value;
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        warn('paginate must be a page size or { size, path }; the page is not paginated');
+        return undefined;
+    }
+    const { size, path } = options;
+    if (typeof size !== 'number' || !Number.isInteger(size) || size < 1) {
+        warn('paginate.size must be a whole number of at least 1; the page is not paginated');
+        return undefined;
+    }
+    if (path === undefined) {
+        return { size, path: DEFAULT_PAGINATION_PATH };
+    }
+    if (typeof path !== 'string' || !PAGINATION_PATH_PATTERN.test(path)) {
+        warn(`paginate.path must be a single URL segment such as "page"; using "${DEFAULT_PAGINATION_PATH}"`);
+        return { size, path: DEFAULT_PAGINATION_PATH };
+    }
+    return { size, path };
+}
+/**
+ * Groups the pages of a collection by the values of a front matter field. Values are slugified
+ * into keys; values that slugify to the same key share one group, under the first value seen.
+ *
+ * @param pages - Collection pages, newest first
+ * @param field - Front matter field holding a string, a number, or a list of them
+ * @param onEmptyKey - Reports a value that slugifies to nothing
+ * @param onCollision - Reports a value merged into the group of another value
+ * @returns The groups, sorted by key
+ */
+function groupByField(pages, field, onEmptyKey, onCollision) {
+    const groups = new Map();
+    for (const page of pages) {
+        const value = page.frontMatter[field];
+        const values = Array.isArray(value) ? value : [value];
+        const pageKeys = new Set();
+        for (const raw of values) {
+            if (typeof raw !== 'string' && !(typeof raw === 'number' && Number.isFinite(raw))) {
+                continue;
+            }
+            const label = String(raw).trim();
+            if (!label) {
+                continue;
+            }
+            const key = slugify(label);
+            if (!key) {
+                onEmptyKey(label);
+                continue;
+            }
+            let group = groups.get(key);
+            if (!group) {
+                group = { key, label, items: [] };
+                groups.set(key, group);
+            }
+            else if (group.label !== label) {
+                onCollision(key, group.label, label);
+            }
+            // A page that lists two values with the same key appears once
+            if (!pageKeys.has(key)) {
+                pageKeys.add(key);
+                group.items.push(page);
+            }
+        }
+    }
+    return [...groups.values()].sort((a, b) => a.key.localeCompare(b.key));
+}
+/**
+ * Turns the pages loaded from Markdown into the pages of a build:
+ *
+ * - Each `[param].md` template is removed and replaced by one page per key: per value of
+ *   `generate.from` in its collection, and per `collections.generate` entry that names it.
+ *   A template that produces no keys produces no output.
+ * - Every page with `paginate`, and every generated page whose template has
+ *   `generate.paginate`, gets one more page per additional slice of its items.
+ *
+ * Generated and pagination pages are virtual: they are never collection members and are left
+ * out of navigation, search and RSS unless they opt in. A virtual page whose URL or output
+ * file is already taken is skipped with a warning.
+ *
+ * @param loaded - Pages loaded from Markdown files
+ * @param config - Stati configuration
+ * @param logger - Logger for warnings
+ * @returns The pages to build: loaded pages without templates, then virtual pages
+ */
+export async function expandPages(loaded, config, logger) {
+    // Source-relative path of a page, such as blog/tags/[tag].md, for template paths and warnings
+    let srcDir;
+    const label = (page) => relative((srcDir ??= resolveSrcDir(config)), page.sourcePath).replace(/\\/g, '/');
+    const reported = new Set();
+    const warnOnce = (message) => {
+        if (!reported.has(message)) {
+            reported.add(message);
+            logger.warning(message);
+        }
+    };
+    const templates = [];
+    const pages = [];
+    for (const page of loaded) {
+        const param = getTemplateParam(page);
+        if (param === undefined) {
+            pages.push(page);
+        }
+        else if (!PARAM_NAME_PATTERN.test(param)) {
+            warnOnce(`${label(page)}: "${param}" is not a valid template parameter (use letters, digits, - and _, such as [tag].md); the file is skipped`);
+        }
+        else {
+            templates.push({ page, param, path: label(page) });
+        }
+    }
+    const collections = getCollections(pages);
+    // Front matter that only works elsewhere, or names a collection that doesn't exist
+    for (const page of pages) {
+        const { collection, generate } = page.frontMatter;
+        if (collection !== undefined && findCollectionPath(collections, collection) === undefined) {
+            warnOnce(`${label(page)}: collection "${String(collection)}" is not the URL of a collection index page; the page reads its default collection`);
+        }
+        if (generate !== undefined) {
+            warnOnce(`${label(page)}: generate only works in a [param].md template, such as site/blog/tags/[tag].md`);
+        }
+    }
+    // Output files taken so far, with the URL that writes each. A later page that would write
+    // one is skipped: /tags/ and /tags/index both write tags/index.html.
+    const outputFileOf = (url) => join(sep, getPageOutputFile(url)).replace(/\\/g, '/');
+    const taken = new Map();
+    for (const page of pages) {
+        const file = outputFileOf(page.url);
+        if (!taken.has(file)) {
+            taken.set(file, page.url);
+        }
+    }
+    const claim = (url, what) => {
+        const file = outputFileOf(url);
+        const owner = taken.get(file);
+        if (owner === url) {
+            warnOnce(`${what} would use the URL ${url}, which another page already has; it is skipped`);
+            return false;
+        }
+        if (owner !== undefined) {
+            warnOnce(`${what} would use the URL ${url}, which writes the same file as ${owner} (${file.slice(1)}); it is skipped`);
+            return false;
+        }
+        taken.set(file, url);
+        return true;
+    };
+    // Pages from collections.generate, grouped by the template they name
+    const entriesByTemplate = new Map();
+    for (const entry of await runGenerateHook(config, pages, logger)) {
+        const template = normalizeTemplatePath(entry.template);
+        const known = templates.some((candidate) => candidate.path === template);
+        if (typeof entry.url !== 'string' || !entry.url.startsWith('/')) {
+            warnOnce(`collections.generate: entry with url ${JSON.stringify(entry.url)} needs a URL starting with "/"; it is skipped`);
+        }
+        else if (!known) {
+            warnOnce(`collections.generate: ${entry.url} names the template ${JSON.stringify(entry.template)}, which is not a [param].md file in the source directory; it is skipped`);
+        }
+        else {
+            const list = entriesByTemplate.get(template) ?? [];
+            list.push(entry);
+            entriesByTemplate.set(template, list);
+        }
+    }
+    const generatedPages = [];
+    for (const { page: template, param, path } of templates) {
+        const fm = template.frontMatter;
+        const generate = fm.generate && typeof fm.generate === 'object' && !Array.isArray(fm.generate)
+            ? fm.generate
+            : undefined;
+        const from = typeof generate?.from === 'string' ? generate.from.trim() : '';
+        const entries = entriesByTemplate.get(path) ?? [];
+        if (fm.generate !== undefined && !generate) {
+            warnOnce(`${path}: generate must be a mapping such as { from: tags }`);
+        }
+        if (fm.paginate !== undefined) {
+            warnOnce(`${path}: use generate.paginate to split generated pages; paginate is ignored here`);
+        }
+        if (!from && entries.length === 0) {
+            warnOnce(`${path}: set generate.from (such as "from: tags") or return pages for it from collections.generate; it generates no pages`);
+            continue;
+        }
+        // The template reads the collection its front matter names, or the one its folder is in
+        const collectionPath = resolveCollectionPath({ ...template, url: template.slug }, pages);
+        const pageUrl = createUrlBuilder(template, param, () => warnOnce(`${path}: permalink must contain [${param}] to give each page its own URL; it is ignored`));
+        const groups = [];
+        if (from) {
+            const collection = collectionPath !== undefined ? collections.byPath.get(collectionPath) : undefined;
+            if (!collection) {
+                warnOnce(`${path}: generate.from needs a collection, but the template is in none; set collection in its front matter, such as "collection: /blog"`);
+            }
+            else {
+                const found = groupByField(collection.recentPages, from, (value) => warnOnce(`${path}: "${value}" has no Latin letters or digits to use in a URL; it gets no page`), (key, kept, merged) => warnOnce(`${path}: "${merged}" and "${kept}" both become the key "${key}"; their pages are listed together under "${kept}"`));
+                for (const group of found) {
+                    groups.push({ ...group, url: pageUrl(group.key) });
+                }
+            }
+        }
+        for (const entry of entries) {
+            const key = typeof entry.key === 'string' && entry.key ? entry.key : lastSegment(entry.url);
+            groups.push({
+                key,
+                label: typeof entry.label === 'string' && entry.label ? entry.label : key,
+                items: Array.isArray(entry.items) ? entry.items : [],
+                url: entry.url,
+                ...(entry.data !== undefined && { data: entry.data }),
+            });
+        }
+        const paginate = parsePaginate(generate?.paginate, (message) => warnOnce(`${path}: generate.${message}`));
+        for (const group of groups) {
+            if (!claim(group.url, `${path} for "${group.label}"`)) {
+                continue;
+            }
+            const generated = {
+                key: group.key,
+                label: group.label,
+                items: group.items,
+                template: path,
+                ...(group.data !== undefined && { data: group.data }),
+            };
+            const frontMatter = substituteFrontMatter(fm, param, group.label);
+            if (collectionPath !== undefined) {
+                frontMatter.collection = collectionPath;
+            }
+            const page = {
+                // The template's slug with the key in place of [param]: /tags/[tag] → /tags/css
+                slug: `${template.slug.slice(0, template.slug.lastIndexOf('/') + 1)}${group.key}`,
+                url: group.url,
+                sourcePath: template.sourcePath,
+                frontMatter,
+                content: template.content,
+                ...(template.publishedAt && { publishedAt: template.publishedAt }),
+                generated,
+            };
+            generatedPages.push(page);
+            if (paginate) {
+                generatedPages.push(...paginatePage(page, group.items, paginate, claim, path));
+            }
+        }
+    }
+    // Listings with paginate: index pages, or pages with a collection in their front matter
+    const paginationPages = [];
+    for (const page of pages) {
+        if (page.frontMatter.paginate === undefined) {
+            continue;
+        }
+        const where = label(page);
+        const settings = parsePaginate(page.frontMatter.paginate, (message) => warnOnce(`${where}: ${message}`));
+        if (!settings) {
+            continue;
+        }
+        const collectionPath = resolveCollectionPath(page, pages);
+        const collection = collectionPath !== undefined ? collections.byPath.get(collectionPath) : undefined;
+        if (!collection) {
+            warnOnce(`${where}: paginate needs a collection, but the page has none; it is not paginated`);
+            continue;
+        }
+        paginationPages.push(...paginatePage(page, collection.recentPages, settings, claim, where, collectionPath));
+    }
+    return [...pages, ...paginationPages, ...generatedPages];
+}
+/**
+ * Sets the first page's pagination data and creates the pages after it.
+ *
+ * @param page - The first page, which keeps its URL
+ * @param items - Everything the listing shows, in order
+ * @param settings - Page size and URL segment
+ * @param claim - Reserves a URL, or reports that it is taken
+ * @param where - Source label for warnings
+ * @param collectionPath - Collection the later pages read; generated pages carry their own
+ * @returns The pages after the first
+ */
+function paginatePage(page, items, settings, claim, where, collectionPath) {
+    const [first, ...rest] = paginateItems(page.url, items, settings);
+    page.pagination = first;
+    const later = [];
+    for (const pagination of rest) {
+        const url = pagination.urls[pagination.pageNumber - 1];
+        if (!claim(url, `Page ${pagination.pageNumber} of ${where}`)) {
+            continue;
+        }
+        const frontMatter = copyValue(page.frontMatter);
+        if (collectionPath !== undefined) {
+            frontMatter.collection = collectionPath;
+        }
+        later.push({
+            ...page,
+            slug: url.length > 1 && url.endsWith('/') ? url.slice(0, -1) : url,
+            url,
+            frontMatter,
+            pagination,
+        });
+    }
+    return later;
+}
+/**
+ * Returns a function that gives the URL of a template's page for a key: the template's URL
+ * with `[param]` replaced, or its `permalink` with `[param]` replaced.
+ */
+function createUrlBuilder(template, param, onBadPermalink) {
+    const token = `[${param}]`;
+    const permalink = template.frontMatter.permalink;
+    if (typeof permalink === 'string') {
+        if (permalink.includes(token)) {
+            return (key) => permalink.split(token).join(key);
+        }
+        onBadPermalink();
+    }
+    // The template's file-based URL ends with the token: /blog/tags/[tag]
+    const base = template.slug.slice(0, -token.length);
+    return (key) => `${base}${key}`;
+}
+/**
+ * Runs `collections.generate`.
+ */
+async function runGenerateHook(config, pages, logger) {
+    const generate = config.collections?.generate;
+    if (typeof generate !== 'function') {
+        return [];
+    }
+    let entries;
+    try {
+        entries = await generate({ config, pages });
+    }
+    catch (error) {
+        throw new Error(`collections.generate failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (!Array.isArray(entries)) {
+        logger.warning('collections.generate must return an array of pages; its result is ignored');
+        return [];
+    }
+    return entries.filter((entry) => {
+        if (entry && typeof entry === 'object' && typeof entry.template === 'string') {
+            return true;
+        }
+        logger.warning('collections.generate: every entry needs a url and a template; an entry is skipped');
+        return false;
+    });
+}
+/**
+ * Normalizes a template path from `collections.generate` to the form expansion uses:
+ * relative to the source directory, with forward slashes and the `.md` extension.
+ */
+function normalizeTemplatePath(template) {
+    const path = template.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+    return path.endsWith('.md') ? path : `${path}.md`;
+}
+function lastSegment(url) {
+    return url.split('/').filter(Boolean).at(-1) ?? '';
+}

package/dist/core/isg/builder.d.ts

@@ -1,4 +1,27 @@
 import type { PageModel, CacheEntry, StatiConfig } from '../../types/index.js';
+import type { PageReads } from '../collections.js';
+/**
+ * What a render discovered: the source images a page displays (`assetDeps`), the generated
+ * images it references (`images`) and the shared data it read (`reads`).
+ */
+export interface RenderedAssets {
+    /** Absolute paths of files whose content affects the page, such as source images */
+    assetDeps: readonly string[];
+    /** Generated image files the page references, relative to the output directory */
+    images: readonly string[];
+    /** Whether the render read the collection and the navigation tree */
+    reads?: PageReads | undefined;
+}
+/**
+ * Whether a cache entry records what its page read while rendering. Entries written before
+ * Stati recorded it don't, and their page must be rebuilt once: whether it depends on its
+ * collection or the navigation tree is unknown, and assuming it doesn't could keep stale
+ * listings or prev/next links.
+ *
+ * @param entry - The cache entry
+ * @returns True when `readsCollection` and `readsNav` are both recorded
+ */
+export declare function hasRecordedReads(entry: CacheEntry): boolean;
 /**
  * Determines if a page should be rebuilt based on ISG logic.
  * Checks content changes, dependency changes, TTL expiration, and freeze status.
@@ -29,6 +52,7 @@ export declare function shouldRebuildPage(page: PageModel, entry: CacheEntry | u
  * @param allPages - All pages in the site, used to resolve the same layout as rendering
  * @param renderedAt - When the page was rendered
  * @param renderInputsHash - Optional hash of asset URLs and injection settings
+ * @param rendered - Files the render discovered, such as images
  * @returns New cache entry
  *
  * @example
@@ -36,7 +60,7 @@ export declare function shouldRebuildPage(page: PageModel, entry: CacheEntry | u
  * const entry = await createCacheEntry(page, config, pages, new Date());
  * ```
  */
-export declare function createCacheEntry(page: PageModel, config: StatiConfig, allPages: PageModel[], renderedAt: Date, renderInputsHash?: string): Promise<CacheEntry>;
+export declare function createCacheEntry(page: PageModel, config: StatiConfig, allPages: PageModel[], renderedAt: Date, renderInputsHash?: string, rendered?: RenderedAssets): Promise<CacheEntry>;
 /**
  * Updates an existing cache entry with new information after rebuilding.
  * In dev mode, this is optimized to reuse the existing deps array since
@@ -49,6 +73,7 @@ export declare function createCacheEntry(page: PageModel, config: StatiConfig, a
  * @param renderedAt - When the page was rendered
  * @param fastUpdate - If true, skip expensive dep tracking (dev mode optimization)
  * @param renderInputsHash - Optional hash of asset URLs and injection settings
+ * @param rendered - Files the render discovered, such as images
  * @returns Updated cache entry
  *
  * @example
@@ -56,5 +81,5 @@ export declare function createCacheEntry(page: PageModel, config: StatiConfig, a
  * const updatedEntry = await updateCacheEntry(existingEntry, page, config, pages, new Date());
  * ```
  */
-export declare function updateCacheEntry(entry: CacheEntry, page: PageModel, config: StatiConfig, allPages: PageModel[], renderedAt: Date, fastUpdate?: boolean, renderInputsHash?: string): Promise<CacheEntry>;
+export declare function updateCacheEntry(entry: CacheEntry, page: PageModel, config: StatiConfig, allPages: PageModel[], renderedAt: Date, fastUpdate?: boolean, renderInputsHash?: string, rendered?: RenderedAssets): Promise<CacheEntry>;
 //# sourceMappingURL=builder.d.ts.map

package/dist/core/isg/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../../src/core/isg/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAqE/E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,SAAS,EAAE,EACrB,GAAG,EAAE,IAAI,EACT,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,OAAO,CAAC,CAoKlB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,SAAS,EAAE,EACrB,UAAU,EAAE,IAAI,EAChB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,UAAU,CAAC,CAqFrB;AAkDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,SAAS,EAAE,EACrB,UAAU,EAAE,IAAI,EAChB,UAAU,UAAQ,EAClB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,UAAU,CAAC,CAmDrB"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../../src/core/isg/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAsFnD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,kFAAkF;IAClF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,qEAAqE;IACrE,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAE3D;AAuDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,SAAS,EAAE,EACrB,GAAG,EAAE,IAAI,EACT,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,OAAO,CAAC,CAuKlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,SAAS,EAAE,EACrB,UAAU,EAAE,IAAI,EAChB,gBAAgB,CAAC,EAAE,MAAM,EACzB,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,UAAU,CAAC,CAmFrB;AAkDD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,SAAS,EAAE,EACrB,UAAU,EAAE,IAAI,EAChB,UAAU,UAAQ,EAClB,gBAAgB,CAAC,EAAE,MAAM,EACzB,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,UAAU,CAAC,CAiErB"}