@stati/core 1.28.0 → 1.29.0

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,14 +1,27 @@
 import type { PageModel, CacheEntry, StatiConfig } from '../../types/index.js';
+import type { PageReads } from '../collections.js';
 /**
- * Files a render discovered: the source images a page displays (`assetDeps`) and the
- * generated images it references (`images`).
+ * 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.

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;AAgF/E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,kFAAkF;IAClF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AA0BD;;;;;;;;;;;;;;;;;;;;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,CAsFrB;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,CA+DrB"}
+{"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"}

package/dist/core/isg/builder.js

@@ -60,8 +60,42 @@ function isValidCacheEntry(entry) {
             return false;
         }
     }
+    for (const flag of [entry.readsCollection, entry.readsNav]) {
+        if (flag !== undefined && typeof flag !== 'boolean') {
+            return false;
+        }
+    }
     return true;
 }
+/**
+ * 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 function hasRecordedReads(entry) {
+    return typeof entry.readsCollection === 'boolean' && typeof entry.readsNav === 'boolean';
+}
+/**
+ * Tags a page's cache entry carries for `stati invalidate "tag:…"`: its front matter tags,
+ * plus the key and label of a generated page, so `tag:css` also refreshes `/tags/css`.
+ */
+function getCacheTags(page) {
+    const tags = Array.isArray(page.frontMatter.tags)
+        ? page.frontMatter.tags.filter((tag) => typeof tag === 'string')
+        : [];
+    if (page.generated) {
+        for (const tag of [page.generated.key, page.generated.label]) {
+            if (tag && !tags.includes(tag)) {
+                tags.push(tag);
+            }
+        }
+    }
+    return tags;
+}
 /**
  * Hashes render-discovered dependencies by content. Missing files hash to a sentinel.
  */
@@ -74,14 +108,19 @@ async function hashAssetDeps(assetDeps) {
 }
 /**
  * Returns the entry with its `assetDeps` and `images` replaced by this render's,
- * dropping the fields when a render found none.
+ * dropping the fields when a render found none, and with what the render read.
  */
 function withRenderedAssets(entry, rendered) {
-    const { assetDeps: _assetDeps, images: _images, ...rest } = entry;
+    const { assetDeps: _assetDeps, images: _images, readsCollection: _readsCollection, readsNav: _readsNav, ...rest } = entry;
     return {
         ...rest,
         ...(rendered && rendered.assetDeps.length > 0 && { assetDeps: [...rendered.assetDeps] }),
         ...(rendered && rendered.images.length > 0 && { images: [...rendered.images] }),
+        // Always written, false included: a missing flag means "unknown" and forces a rebuild
+        ...(rendered?.reads && {
+            readsCollection: rendered.reads.collection,
+            readsNav: rendered.reads.nav,
+        }),
     };
 }
 /**
@@ -279,10 +318,7 @@ export async function createCacheEntry(page, config, allPages, renderedAt, rende
     timings.depsHashes = performance.now() - start;
     const inputsHash = computeInputsHash(contentHash, depsHashes, renderInputsHash);
     // Extract tags from front matter
-    let tags = [];
-    if (Array.isArray(page.frontMatter.tags)) {
-        tags = page.frontMatter.tags.filter((tag) => typeof tag === 'string');
-    }
+    const tags = getCacheTags(page);
     // Get published date
     const publishedAt = getPublishedDateISO(page);
     // Compute effective TTL
@@ -418,6 +454,8 @@ export async function updateCacheEntry(entry, page, config, allPages, renderedAt
             return withRenderedAssets({
                 ...entry,
                 inputsHash,
+                // Front matter tags, and a generated page's label, can change without a layout change
+                tags: getCacheTags(page),
                 renderedAt: renderedAt.toISOString(),
             }, rendered);
         }

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

@@ -61,8 +61,10 @@ export declare function computeBinaryFileHash(filePath: string): Promise<string>
  */
 export declare function computeInputsHash(contentHash: string, depsHashes: string[], renderInputsHash?: string): string;
 /**
- * Computes a hash of the navigation tree structure.
- * Used to detect when navigation has changed (title, url, order, children structure).
+ * Computes a hash of the navigation tree.
+ * Covers every field of a navigation node (title, url, path, order, publishedAt,
+ * isCollection and children), so pages that read the navigation rebuild when any of
+ * what they can show changes.
  *
  * @param navigation - The navigation tree to hash
  * @returns SHA-256 hash as a hex string

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

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/core/isg/hash.ts"],"names":[],"mappings":"AAgCA;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAiBhG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8B9E;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAAE,EACpB,gBAAgB,CAAC,EAAE,MAAM,GACxB,MAAM,CASR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,CAqCnE"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/core/isg/hash.ts"],"names":[],"mappings":"AAgCA;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAmBhG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8B9E;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAAE,EACpB,gBAAgB,CAAC,EAAE,MAAM,GACxB,MAAM,CASR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,CA+CnE"}

package/dist/core/isg/hash.js

@@ -52,6 +52,9 @@ export function computeContentHash(content, frontMatter) {
     const sortKeys = (obj) => {
         if (obj === null || typeof obj !== 'object')
             return obj;
+        // A date has no keys to sort; kept as it is, it serializes as its ISO string, not {}
+        if (obj instanceof Date)
+            return obj;
         if (Array.isArray(obj))
             return obj.map(sortKeys);
         const sorted = {};
@@ -144,8 +147,10 @@ export function computeInputsHash(contentHash, depsHashes, renderInputsHash) {
     ]);
 }
 /**
- * Computes a hash of the navigation tree structure.
- * Used to detect when navigation has changed (title, url, order, children structure).
+ * Computes a hash of the navigation tree.
+ * Covers every field of a navigation node (title, url, path, order, publishedAt,
+ * isCollection and children), so pages that read the navigation rebuild when any of
+ * what they can show changes.
  *
  * @param navigation - The navigation tree to hash
  * @returns SHA-256 hash as a hex string
@@ -162,9 +167,18 @@ export function computeNavigationHash(navigation) {
             title: String(node.title ?? ''),
             url: String(node.url ?? ''),
         };
+        if (typeof node.path === 'string') {
+            normalized.path = node.path;
+        }
         if (node.order !== undefined && typeof node.order === 'number') {
             normalized.order = node.order;
         }
+        if (node.publishedAt instanceof Date && !Number.isNaN(node.publishedAt.getTime())) {
+            normalized.publishedAt = node.publishedAt.toISOString();
+        }
+        if (typeof node.isCollection === 'boolean') {
+            normalized.isCollection = node.isCollection;
+        }
         if (node.children && Array.isArray(node.children) && node.children.length > 0) {
             normalized.children = node.children.map((child) => normalizeNavNode(child));
         }