@stati/core 1.28.0 → 1.29.0

package/README.md

@@ -166,7 +166,8 @@ Customize layouts with [Eta templates](https://eta.js.org):
 
 Only rebuild what changed:
 
-- Smart caching based on hashes of each page's content and templates
+- Smart caching based on hashes of each page's content and templates, and of the collection and navigation data it reads
+- Removal of pages that no longer exist, such as deleted posts and unused tag pages
 - TTL-based refresh for dynamic content
 - Tag-based invalidation for related content
 
@@ -183,6 +184,10 @@ await invalidate('path:/posts');
 await invalidate('age:3months');
 ```
 
+#### Collections, Pagination and Generated Pages
+
+A folder with an `index.md` is a collection: templates read its pages as `stati.collection`, sorted by date and grouped by tag. `paginate: 10` in front matter splits a listing into `/blog`, `/blog/page/2` and so on (`stati.pagination`), and a `[tag].md` template becomes one page per tag (`stati.generated`). See [Collections and generated pages](https://stati.build/core-concepts/collections).
+
 #### Built-In SEO
 
 SEO optimization works automatically with zero configuration:

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

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/core/build.ts"],"names":[],"mappings":"AA2DA,OAAO,KAAK,EAEV,UAAU,EACV,MAAM,EASP,MAAM,mBAAmB,CAAC;AAK3B,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,iCAAiC;IACjC,OAAO,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACrC,uEAAuE;IACvE,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,sGAAsG;IACtG,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAkGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsB5E"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/core/build.ts"],"names":[],"mappings":"AAuEA,OAAO,KAAK,EAEV,UAAU,EACV,MAAM,EASP,MAAM,mBAAmB,CAAC;AAK3B,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,iCAAiC;IACjC,OAAO,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACrC,uEAAuE;IACvE,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,sGAAsG;IACtG,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAkGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsB5E"}

package/dist/core/build.js

@@ -1,15 +1,17 @@
-import { ensureDir, writeFile, remove, pathExists, stat, readdir, copyFile, resolveOutDir, resolveStaticDir, resolveCacheDir, enableInventoryTracking, disableInventoryTracking, clearInventory, writeTailwindClassInventory, getInventorySize, isTailwindUsed, loadPreviousInventory, compileTypeScript, detectExistingBundles, autoInjectBundles, getBundlePathsForPage, formatBytes, } from './utils/index.js';
+import { ensureDir, writeFile, remove, pathExists, stat, readdir, copyFile, resolveOutDir, resolveStaticDir, resolveCacheDir, enableInventoryTracking, disableInventoryTracking, clearInventory, writeTailwindClassInventory, getInventorySize, isTailwindUsed, loadPreviousInventory, compileTypeScript, detectExistingBundles, autoInjectBundles, getBundlePathsForPage, formatBytes, isVirtualPage, getPageOutputFile, } from './utils/index.js';
 import { join, dirname, relative, posix } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { loadConfig } from '../config/loader.js';
 import { loadContent } from './content.js';
+import { expandPages } from './expand.js';
+import { createSummaryHasher, resolveCollectionPath, resolveSummaryFields, } from './collections.js';
 import { createMarkdownProcessor, renderMarkdown, extractToc } from './markdown.js';
 import { createTemplateEngine, renderPage } from './templates.js';
 import { buildNavigation } from './navigation.js';
-import { loadCacheManifest, saveCacheManifest, shouldRebuildPage, createCacheEntry, updateCacheEntry, withBuildLock, computeNavigationHash, computeContentHash, clearFileHashCache, clearTemplatePathCache, } from './isg/index.js';
+import { loadCacheManifest, saveCacheManifest, shouldRebuildPage, createCacheEntry, updateCacheEntry, hasRecordedReads, pruneOrphanedPages, withBuildLock, computeNavigationHash, computeContentHash, clearFileHashCache, clearTemplatePathCache, } from './isg/index.js';
 import { generateSitemap, generateRobotsTxtFromConfig, autoInjectSEO, } from '../seo/index.js';
 import { generateRSSFeeds, validateRSSConfig } from '../rss/index.js';
-import { computeSearchIndexFilename, generateSearchIndex, writeSearchIndex, autoInjectSearchMeta, } from '../search/index.js';
+import { computeSearchIndexFilename, generateSearchIndex, writeSearchIndex, autoInjectSearchMeta, isGeneratedPageExcludedFromSearch, } from '../search/index.js';
 import { getEnv, isDevelopment } from '../env.js';
 import { DEFAULT_OUT_DIR } from '../constants.js';
 import { ImageRuntime } from '../images/runtime.js';
@@ -180,12 +182,18 @@ async function setupCacheAndManifest(cacheDir) {
     return { manifest };
 }
 /**
- * Loads content and builds navigation.
+ * Loads content, expands generated and paginated pages, and builds navigation.
  */
 async function loadContentAndBuildNavigation(config, options, logger) {
-    // Load all content
-    const pages = await loadContent(config, options.includeDrafts);
-    logger.status(`Found ${pages.length} pages`);
+    // Load all content, then replace [param].md templates with their pages and add the
+    // pages of paginated listings. Navigation, SEO, sitemap and search see the result.
+    const loaded = await loadContent(config, options.includeDrafts);
+    const pages = await expandPages(loaded, config, logger);
+    const virtualCount = pages.filter((page) => isVirtualPage(page)).length;
+    logger.status(`Found ${pages.length - virtualCount} pages`);
+    if (virtualCount > 0) {
+        logger.status(`Generated ${virtualCount} more from templates and pagination`);
+    }
     // Build navigation from pages
     if (logger.step) {
         console.log(); // Add spacing before navigation step
@@ -202,31 +210,35 @@ async function loadContentAndBuildNavigation(config, options, logger) {
     // Create processors
     const md = await createMarkdownProcessor(config);
     const eta = createTemplateEngine(config);
-    return { pages, navigation, md, eta, navigationHash };
+    return { pages, markdownFiles: loaded.length, navigation, md, eta, navigationHash };
 }
 /**
  * Output file and ISG cache key of a page.
  */
 function getPageOutput(page, outDir) {
-    let outputPath;
-    if (page.url === '/') {
-        outputPath = join(outDir, 'index.html');
-    }
-    else if (page.url.endsWith('/')) {
-        outputPath = join(outDir, page.url, 'index.html');
-    }
-    else {
-        outputPath = join(outDir, `${page.url}.html`);
-    }
+    const outputPath = join(outDir, getPageOutputFile(page.url));
     // Cache key is the output path relative to outDir
     const relativePath = relative(outDir, outputPath).replace(/\\/g, '/');
     const cacheKey = relativePath.startsWith('/') ? relativePath : `/${relativePath}`;
     return { outputPath, cacheKey };
 }
+/**
+ * Hashes a value for the render inputs, or returns a value that never matches when it
+ * cannot be serialized, so the page rebuilds instead of keeping stale output.
+ */
+function hashableData(value) {
+    try {
+        JSON.stringify(value);
+        return value ?? null;
+    }
+    catch {
+        return `unserializable:${Date.now()}:${Math.random()}`;
+    }
+}
 /**
  * Processes pages with ISG caching logic.
  */
-async function processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder = noopMetricRecorder, searchIndexFilename, imageRuntime = null) {
+async function processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder = noopMetricRecorder, searchIndexFilename, imageRuntime = null, navigationHash = computeNavigationHash(navigation)) {
     let cacheHits = 0;
     let cacheMisses = 0;
     const searchablePages = [];
@@ -238,6 +250,18 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         await config.hooks.beforeAll(buildContext);
         endHookBeforeAll();
     }
+    // Collection summaries, hashed after beforeAll because the hook can change front matter
+    const summaries = createSummaryHasher(pages, resolveSummaryFields(config));
+    // The pages of a listing share one array of page URLs, hashed once for all of them
+    const urlListHashes = new WeakMap();
+    const hashUrlList = (urls) => {
+        let hash = urlListHashes.get(urls);
+        if (hash === undefined) {
+            hash = computeContentHash('', { urls });
+            urlListHashes.set(urls, hash);
+        }
+        return hash;
+    };
     // Render each page with progress tracking and ISG
     if (logger.step) {
         logger.step(2, 3, 'Rendering pages');
@@ -273,18 +297,56 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
                 searchIndexPath: `/${searchIndexFilename}`,
             }),
         };
-        const renderInputsHash = computeContentHash('', {
+        // Collection the page sees as stati.collection; a page whose collection appears,
+        // disappears or changes rebuilds even when it never read it
+        const collectionPath = resolveCollectionPath(page, pages);
+        const staticRenderInputs = {
             ...assets,
             bundleAutoInject: config.typescript?.autoInject !== false,
             searchAutoInject: config.search?.autoInjectMetaTag !== false,
             // Omitted with images: false, so the hash matches builds without the image pipeline
             ...(imageFingerprint && { images: imageFingerprint }),
+            collection: collectionPath ?? null,
+            // A listing page depends on its own slice and on the page count, which every page
+            // shows in its numbered links
+            ...(page.pagination && {
+                pagination: {
+                    pageNumber: page.pagination.pageNumber,
+                    totalPages: page.pagination.totalPages,
+                    urls: hashUrlList(page.pagination.urls),
+                    items: summaries.pages(page.pagination.items),
+                },
+            }),
+            // A generated page depends on its own items only, not on the whole collection
+            ...(page.generated && {
+                generated: {
+                    key: page.generated.key,
+                    label: page.generated.label,
+                    template: page.generated.template,
+                    items: summaries.pages(page.generated.items),
+                    data: hashableData(page.generated.data),
+                },
+            }),
+        };
+        // The data a render read: the collection summary and the navigation tree
+        const renderInputsHashFor = (reads) => computeContentHash('', {
+            ...staticRenderInputs,
+            ...(reads?.collection && {
+                collectionSummary: collectionPath !== undefined ? summaries.collection(collectionPath) : 'none',
+            }),
+            ...(reads?.nav && { navigation: navigationHash }),
         });
+        // Entries written before Stati recorded what pages read are rebuilt once to record it
+        const readsKnown = existingEntry !== undefined && hasRecordedReads(existingEntry);
+        const renderInputsHash = renderInputsHashFor(readsKnown
+            ? { collection: existingEntry.readsCollection, nav: existingEntry.readsNav }
+            : undefined);
         // Check if we should rebuild this page (considering ISG logic)
         const shouldRebuildStart = performance.now();
         const shouldRebuild = options.force ||
             config.isg?.enabled === false ||
             !(await pathExists(outputPath)) ||
+            (existingEntry !== undefined && !readsKnown) ||
             // A cached page whose generated images are gone is rebuilt to regenerate them
             (imageRuntime !== null && !imageRuntime.outputsExist(existingEntry?.images)) ||
             (await shouldRebuildPage(page, existingEntry, config, pages, buildTime, renderInputsHash));
@@ -300,7 +362,7 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
             recorder.recordPageTiming(page.url, 0, true);
             // Collect searchable page data for cached pages if search is enabled
             // Extract TOC without full HTML rendering for efficiency
-            if (config.search?.enabled === true) {
+            if (config.search?.enabled === true && !isGeneratedPageExcludedFromSearch(page)) {
                 const tocEnabled = config.markdown?.toc !== false;
                 const toc = tocEnabled ? extractToc(page.content, md) : [];
                 searchablePages.push({ page, toc, markdownContent: page.content });
@@ -357,10 +419,17 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         if (config.typescript?.autoInject !== false && assets.bundlePaths.length > 0) {
             finalHtml = autoInjectBundles(finalHtml, assets.bundlePaths);
         }
-        // Start the image jobs the final HTML needs and record its image files for the cache
-        const renderedAssets = pageImages && imageRuntime
+        // Start the image jobs the final HTML needs and record its image files for the cache,
+        // along with what the render read, which decides the hash it is stored under
+        const committedImages = pageImages && imageRuntime
             ? imageRuntime.commitPage(pageImages, finalHtml, { outputPath, cacheKey })
             : undefined;
+        const renderedAssets = {
+            assetDeps: committedImages?.assetDeps ?? [],
+            images: committedImages?.images ?? [],
+            reads: renderResult.reads,
+        };
+        const renderedInputsHash = renderInputsHashFor(renderResult.reads);
         const renderTime = Math.round(performance.now() - startTime);
         // Record page timing for rendered pages (includes template count)
         recorder.recordPageTiming(page.url, renderTime, false, renderResult.templatesLoaded);
@@ -370,7 +439,13 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         // In dev mode, batch writes for parallel execution to avoid Windows filesystem slowdown
         if (isDevMode) {
             pendingWrites.push({ outputPath, content: finalHtml });
-            pendingCacheUpdates.push({ cacheKey, page, existingEntry, renderInputsHash, renderedAssets });
+            pendingCacheUpdates.push({
+                cacheKey,
+                page,
+                existingEntry,
+                renderInputsHash: renderedInputsHash,
+                renderedAssets,
+            });
         }
         else {
             // Production mode: write immediately
@@ -382,17 +457,17 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
             if (!options.skipCacheUpdate) {
                 const cacheEntryStart = performance.now();
                 if (existingEntry) {
-                    manifest.entries[cacheKey] = await updateCacheEntry(existingEntry, page, config, pages, buildTime, false, renderInputsHash, renderedAssets);
+                    manifest.entries[cacheKey] = await updateCacheEntry(existingEntry, page, config, pages, buildTime, false, renderedInputsHash, renderedAssets);
                 }
                 else {
-                    manifest.entries[cacheKey] = await createCacheEntry(page, config, pages, buildTime, renderInputsHash, renderedAssets);
+                    manifest.entries[cacheKey] = await createCacheEntry(page, config, pages, buildTime, renderedInputsHash, renderedAssets);
                 }
                 totalCacheEntryTime += performance.now() - cacheEntryStart;
             }
         }
         // Collect searchable page data if search is enabled
         // Uses TOC entries and markdown content instead of parsing rendered HTML
-        if (config.search?.enabled === true) {
+        if (config.search?.enabled === true && !isGeneratedPageExcludedFromSearch(page)) {
             searchablePages.push({ page, toc, markdownContent: page.content });
         }
         // Run afterRender hook
@@ -567,14 +642,13 @@ async function buildInternal(options = {}) {
         console.log(); // Add spacing before content loading
     }
     const endContentSpan = recorder.startSpan('contentDiscoveryMs');
-    const { pages, navigation, md, eta, navigationHash } = await loadContentAndBuildNavigation(config, options, logger);
+    const { pages, markdownFiles, navigation, md, eta, navigationHash } = await loadContentAndBuildNavigation(config, options, logger);
     endContentSpan();
-    // Record content discovery counts.
-    // Both totalPages and markdownFilesProcessed are incremented by pages.length
-    // because loadContent() only processes *.md files, so all pages are markdown files.
+    // Record content discovery counts. Pages include the ones generated from [param].md
+    // templates and pagination; Markdown files include the templates.
     recorder.increment('totalPages', pages.length);
-    recorder.increment('markdownFilesProcessed', pages.length);
-    // Store navigation hash in manifest for change detection in dev server
+    recorder.increment('markdownFilesProcessed', markdownFiles);
+    // Recorded in the manifest; pages that read the navigation also hash it into their inputs
     manifest.navigationHash = navigationHash;
     // Compile TypeScript if enabled
     // In dev mode, skip compilation since esbuild watcher handles it
@@ -626,9 +700,23 @@ async function buildInternal(options = {}) {
     }
     const endPageRenderSpan = recorder.startSpan('pageRenderingMs');
     const buildTime = new Date();
-    const pageProcessingResult = await processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder, searchIndexFilename, imageRuntime);
+    const pageProcessingResult = await processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder, searchIndexFilename, imageRuntime, navigationHash);
     endPageRenderSpan();
     const { cacheHits, cacheMisses, searchablePages } = pageProcessingResult;
+    // Remove the output of pages that no longer exist, such as a deleted post or a tag no post
+    // uses anymore. Runs before static assets are copied, so a file in the static directory at
+    // the same path is copied afterwards.
+    const liveCacheKeys = new Set(pages.map((page) => getPageOutput(page, outDir).cacheKey));
+    const pruned = await pruneOrphanedPages(manifest, liveCacheKeys, outDir);
+    for (const failure of pruned.failed) {
+        logger.warning(`Could not remove the stale page ${failure.key}: ${failure.message}`);
+    }
+    if (pruned.removed.length > 0) {
+        const count = pruned.removed.length;
+        logger.info(count === 1
+            ? 'Removed 1 page that no longer exists'
+            : `Removed ${count} pages that no longer exist`);
+    }
     // Wait for image jobs; pages whose images failed are rewritten to show plain images
     let imageFailures = [];
     if (imageRuntime) {

package/dist/core/collections.d.ts

@@ -0,0 +1,139 @@
+import type { PageModel, CollectionData, PaginationData, GeneratedPageData, StatiConfig } from '../types/index.js';
+/**
+ * Front matter fields of the collection summary when `collections.summaryFields` is not set.
+ */
+export declare const DEFAULT_SUMMARY_FIELDS: readonly string[];
+/**
+ * The collections of a page list.
+ */
+export interface CollectionIndex {
+    /** Collection data by the URL of its index page */
+    byPath: Map<string, CollectionData>;
+}
+/**
+ * What a render read from data shared between pages. Filled in while the page renders.
+ */
+export interface PageReads {
+    /** The page read `stati.collection` */
+    collection: boolean;
+    /** The page read the navigation tree (`stati.nav` or `stati.page.navNode`) */
+    nav: boolean;
+}
+/**
+ * Returns the collections of a page list, computing them once per array.
+ *
+ * @param allPages - All pages of the build
+ * @returns The collections by index page URL
+ */
+export declare function getCollections(allPages: PageModel[]): CollectionIndex;
+/**
+ * Computes every collection of a page list in one pass.
+ *
+ * A collection belongs to a collection index page (see `isCollectionIndexPage`), or to a page
+ * loaded from an `index.md`, whose collection is empty while its folder holds no pages. The
+ * root collection holds the top-level pages; any other collection holds every page below its
+ * folder, at any depth. The index page itself, generated pages and pagination pages are
+ * never members.
+ *
+ * @param allPages - All pages of the build
+ * @returns The collections by index page URL
+ */
+export declare function buildCollections(allPages: PageModel[]): CollectionIndex;
+/**
+ * Sorts pages by publishedAt date (most recent first), falling back to alphabetical by title.
+ *
+ * @param pages - Pages to sort, in place
+ * @returns The sorted array
+ */
+export declare function sortPagesByDate(pages: PageModel[]): PageModel[];
+/**
+ * Finds the collection a `collection` front matter value names. Accepts the index page URL
+ * with or without a leading or trailing slash: `posts`, `/posts` and `/posts/` all name the
+ * collection of `site/posts/index.md`.
+ *
+ * @param index - The collections of the build
+ * @param value - The front matter value
+ * @returns The index page URL, or undefined when the value names no collection
+ */
+export declare function findCollectionPath(index: CollectionIndex, value: unknown): string | undefined;
+/**
+ * Finds the collection a page reads as `stati.collection`:
+ *
+ * 1. The collection its `collection` front matter field names, when that collection exists.
+ * 2. Its own collection, when the page is a collection index page or an `index.md`, even
+ *    when that collection is empty.
+ * 3. Otherwise the nearest collection with pages that the page belongs to: `/blog/post` reads
+ *    `/blog`, and a top-level page reads the root collection.
+ *
+ * Pagination pages after the first read the collection of the first page. Generated pages
+ * read only the collection their template names; expansion sets it in their front matter.
+ *
+ * @param page - The page
+ * @param allPages - All pages of the build
+ * @returns The index page URL of the collection, or undefined when the page has none
+ */
+export declare function resolveCollectionPath(page: PageModel, allPages: PageModel[]): string | undefined;
+/**
+ * Returns the front matter fields of the collection summary.
+ *
+ * @param config - Stati configuration
+ * @returns `collections.summaryFields`, or the default fields
+ */
+export declare function resolveSummaryFields(config: StatiConfig): readonly string[];
+/**
+ * Hashes what a listing shows of a list of pages: each page's URL, publish date and summary
+ * fields, in list order. The Markdown body only counts when `fields` includes `content`.
+ *
+ * @param pages - The listed pages
+ * @param fields - Front matter fields to include
+ * @returns A `sha256-…` hash
+ */
+export declare function computePagesSummaryHash(pages: readonly PageModel[], fields: readonly string[]): string;
+/**
+ * Collection summary hashes for one build, computed at most once per collection.
+ */
+export interface SummaryHasher {
+    /** Summary hash of a collection, or `'none'` when there is no such collection */
+    collection(path: string): string;
+    /** Summary hash of a list of pages */
+    pages(pages: readonly PageModel[]): string;
+}
+/**
+ * Creates the summary hasher of a build. Call it after the `beforeAll` hook, which can change
+ * the front matter the summaries include.
+ *
+ * @param allPages - All pages of the build
+ * @param fields - Summary fields
+ * @returns The hasher
+ */
+export declare function createSummaryHasher(allPages: PageModel[], fields: readonly string[]): SummaryHasher;
+/**
+ * Wraps collection data for one render. Reading any of its properties sets `reads.collection`,
+ * so the cache knows the page depends on the collection. Arrays and objects are copied on
+ * first read, so a template that sorts or changes them cannot affect other pages, which share
+ * the collection data within a build.
+ *
+ * The properties are accessors on a plain object, not a Proxy, so spreading the template
+ * context (as callable partials do) passes the view along without reading it.
+ *
+ * @param data - The shared collection data
+ * @param reads - The render's read flags
+ * @returns The view for `stati.collection`
+ */
+export declare function createCollectionView(data: CollectionData, reads: PageReads): CollectionData;
+/**
+ * Copies a page's pagination data for `stati.pagination`, so a template that changes the
+ * lists cannot change what the cache hashes.
+ *
+ * @param data - The page's pagination data
+ * @returns A copy with its own arrays
+ */
+export declare function copyPaginationData(data: PaginationData): PaginationData;
+/**
+ * Copies a page's generated data for `stati.generated`.
+ *
+ * @param data - The page's generated data
+ * @returns A copy with its own items array
+ */
+export declare function copyGeneratedData(data: GeneratedPageData): GeneratedPageData;
+//# sourceMappingURL=collections.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collections.d.ts","sourceRoot":"","sources":["../../src/core/collections.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAU3B;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAA8C,CAAC;AAEnG;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,UAAU,EAAE,OAAO,CAAC;IACpB,8EAA8E;IAC9E,GAAG,EAAE,OAAO,CAAC;CACd;AASD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,eAAe,CAQrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,eAAe,CAwBvE;AAwFD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAc/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAc7F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,GAAG,SAAS,CAuBhG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,MAAM,EAAE,CAM3E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,MAAM,CAWR;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,sCAAsC;IACtC,KAAK,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,EAAE,EACrB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,aAAa,CAcf;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,GAAG,cAAc,CAwB3F;AAaD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,CAE5E"}