@stati/core 1.28.0 → 1.29.1

package/dist/core/collections.js

@@ -0,0 +1,342 @@
+import { basename } from 'node:path';
+import { getCollectionPathForPage, getFirstPaginationPage, isCollectionIndexPage, isVirtualPage, } from './utils/index.js';
+import { computeContentHash } from './isg/hash.js';
+import { MARKDOWN_EXTENSION } from '../constants.js';
+/**
+ * Front matter fields of the collection summary when `collections.summaryFields` is not set.
+ */
+export const DEFAULT_SUMMARY_FIELDS = ['title', 'description', 'tags', 'draft'];
+/**
+ * Collections per page list, computed at the first lookup for an array and reused after that.
+ * Like the directory prefix index in `isCollectionIndexPage`, the result is a snapshot: in a
+ * build the first lookup happens in the render loop, after the `beforeAll` hook.
+ */
+const collectionCache = new WeakMap();
+/**
+ * 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 function getCollections(allPages) {
+    const cached = collectionCache.get(allPages);
+    if (cached) {
+        return cached;
+    }
+    const index = buildCollections(allPages);
+    collectionCache.set(allPages, index);
+    return index;
+}
+/**
+ * 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 function buildCollections(allPages) {
+    const pages = allPages.filter((page) => !isVirtualPage(page));
+    const members = new Map();
+    for (const page of pages) {
+        if (!members.has(page.url) &&
+            (isFolderIndexPage(page) || isCollectionIndexPage(page, allPages))) {
+            members.set(page.url, []);
+        }
+    }
+    for (const page of pages) {
+        for (const path of collectionsContaining(page.url, (path) => members.has(path))) {
+            members.get(path).push(page);
+        }
+    }
+    const byPath = new Map();
+    for (const [path, collectionPages] of members) {
+        byPath.set(path, createCollectionData(path, collectionPages));
+    }
+    return { byPath };
+}
+/**
+ * Whether a page was loaded from a folder's `index.md`. The folder is a collection even before
+ * it holds any pages, so an empty blog lists no posts instead of reading another collection.
+ */
+function isFolderIndexPage(page) {
+    return basename(page.sourcePath, MARKDOWN_EXTENSION) === 'index';
+}
+/**
+ * Lists the collections a URL belongs to, outermost first.
+ *
+ * @param url - A page URL
+ * @param isCollection - Whether a URL is a collection index page
+ * @returns Index page URLs
+ */
+function collectionsContaining(url, isCollection) {
+    const found = [];
+    // Every folder the URL lives in, from the outermost: /blog/2024/recap is in /blog/ and /blog/2024/
+    for (let i = url.indexOf('/', 1); i !== -1; i = url.indexOf('/', i + 1)) {
+        const folder = url.slice(0, i + 1);
+        // A folder's index page is usually /blog, or /blog/ with a trailing-slash permalink
+        for (const path of [folder.slice(0, -1), folder]) {
+            if (path !== url && isCollection(path)) {
+                found.push(path);
+            }
+        }
+    }
+    // The root collection is shallow: only pages whose parent is the root belong to it
+    if (url !== '/' && isCollection('/') && getCollectionPathForPage(url) === '/') {
+        found.push('/');
+    }
+    return found;
+}
+/**
+ * Builds the collection data of one index page from its members.
+ */
+function createCollectionData(collectionPath, collectionPages) {
+    // Direct children are one level below the index page
+    const children = collectionPages.filter((page) => {
+        const relativePath = page.url.substring(collectionPath.length);
+        const cleanPath = relativePath.startsWith('/') ? relativePath.substring(1) : relativePath;
+        return !cleanPath.includes('/');
+    });
+    return {
+        pages: collectionPages,
+        children,
+        recentPages: sortPagesByDate([...collectionPages]),
+        pagesByTag: groupPagesByTags(collectionPages),
+        metadata: {
+            totalPages: collectionPages.length,
+            hasChildren: children.length > 0,
+            collectionPath,
+            collectionName: collectionPath === '/' ? 'Home' : basename(collectionPath),
+        },
+    };
+}
+/**
+ * Groups pages by their tags.
+ *
+ * @param pages - Pages to group
+ * @returns Object mapping tag names to arrays of pages
+ */
+function groupPagesByTags(pages) {
+    // No prototype, so tags such as `constructor` or `__proto__` are keys like any other
+    const pagesByTag = Object.create(null);
+    for (const page of pages) {
+        const tags = page.frontMatter.tags;
+        if (Array.isArray(tags)) {
+            for (const tag of tags) {
+                if (typeof tag === 'string') {
+                    (pagesByTag[tag] ??= []).push(page);
+                }
+            }
+        }
+    }
+    return pagesByTag;
+}
+/**
+ * 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 function sortPagesByDate(pages) {
+    return pages.sort((a, b) => {
+        // Sort by publishedAt (newest first)
+        if (a.publishedAt && b.publishedAt) {
+            return b.publishedAt.getTime() - a.publishedAt.getTime();
+        }
+        if (a.publishedAt && !b.publishedAt)
+            return -1;
+        if (!a.publishedAt && b.publishedAt)
+            return 1;
+        // Fallback to title
+        const titleA = a.frontMatter.title || basename(a.url) || 'Untitled';
+        const titleB = b.frontMatter.title || basename(b.url) || 'Untitled';
+        return titleA.localeCompare(titleB);
+    });
+}
+/**
+ * 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 function findCollectionPath(index, value) {
+    if (typeof value !== 'string' || !value.trim()) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    const url = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    if (index.byPath.has(url)) {
+        return url;
+    }
+    if (url === '/') {
+        return undefined;
+    }
+    const alternate = url.endsWith('/') ? url.slice(0, -1) : `${url}/`;
+    return index.byPath.has(alternate) ? alternate : 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 function resolveCollectionPath(page, allPages) {
+    const index = getCollections(allPages);
+    const named = findCollectionPath(index, page.frontMatter.collection);
+    if (named !== undefined) {
+        return named;
+    }
+    if (page.generated) {
+        return undefined;
+    }
+    if ((page.pagination?.pageNumber ?? 1) > 1) {
+        const first = getFirstPaginationPage(page, allPages);
+        return first && !isVirtualPage(first) ? resolveCollectionPath(first, allPages) : undefined;
+    }
+    if (index.byPath.has(page.url)) {
+        return page.url;
+    }
+    // A page always has pages in the collections it belongs to; only a [param].md template can
+    // sit in an empty one, and site/blog/tags/[tag].md reads /blog even with a tags/index.md
+    return collectionsContaining(page.url, (path) => (index.byPath.get(path)?.pages.length ?? 0) > 0).at(-1);
+}
+/**
+ * Returns the front matter fields of the collection summary.
+ *
+ * @param config - Stati configuration
+ * @returns `collections.summaryFields`, or the default fields
+ */
+export function resolveSummaryFields(config) {
+    const fields = config.collections?.summaryFields;
+    if (!Array.isArray(fields)) {
+        return DEFAULT_SUMMARY_FIELDS;
+    }
+    return fields.filter((field) => typeof field === 'string' && field !== '');
+}
+/**
+ * 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 function computePagesSummaryHash(pages, fields) {
+    return computeContentHash('', {
+        fields: [...fields],
+        pages: pages.map((page) => [
+            page.url,
+            toIsoDate(page.publishedAt),
+            ...fields.map((field) => field === 'content' ? page.content : (page.frontMatter[field] ?? null)),
+        ]),
+    });
+}
+function toIsoDate(date) {
+    return date instanceof Date && !Number.isNaN(date.getTime()) ? date.toISOString() : null;
+}
+/**
+ * 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 function createSummaryHasher(allPages, fields) {
+    const memo = new Map();
+    return {
+        collection(path) {
+            let hash = memo.get(path);
+            if (hash === undefined) {
+                const data = getCollections(allPages).byPath.get(path);
+                hash = data ? computePagesSummaryHash(data.pages, fields) : 'none';
+                memo.set(path, hash);
+            }
+            return hash;
+        },
+        pages: (pages) => computePagesSummaryHash(pages, fields),
+    };
+}
+const COLLECTION_KEYS = ['pages', 'children', 'recentPages', 'pagesByTag', 'metadata'];
+/**
+ * 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 function createCollectionView(data, reads) {
+    const view = {};
+    for (const key of COLLECTION_KEYS) {
+        let value;
+        let copied = false;
+        Object.defineProperty(view, key, {
+            enumerable: true,
+            configurable: true,
+            get() {
+                reads.collection = true;
+                if (!copied) {
+                    value = copyCollectionValue(data[key]);
+                    copied = true;
+                }
+                return value;
+            },
+            set(next) {
+                reads.collection = true;
+                value = next;
+                copied = true;
+            },
+        });
+    }
+    return view;
+}
+function copyCollectionValue(value) {
+    if (Array.isArray(value)) {
+        return [...value];
+    }
+    const copy = Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, Array.isArray(entry) ? [...entry] : entry]));
+    // pagesByTag has no prototype, and neither has its copy, so any tag stays a plain key
+    return Object.setPrototypeOf(copy, Object.getPrototypeOf(value));
+}
+/**
+ * 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 function copyPaginationData(data) {
+    return { ...data, items: [...data.items], urls: [...data.urls] };
+}
+/**
+ * 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 function copyGeneratedData(data) {
+    return { ...data, items: [...data.items] };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/core/content.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,aAAa,CAAC,EAAE,OAAO,GACtB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB"}
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/core/content.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,aAAa,CAAC,EAAE,OAAO,GACtB,OAAO,CAAC,SAAS,EAAE,CAAC,CAiDtB"}

package/dist/core/content.js

@@ -39,7 +39,8 @@ export async function loadContent(config, includeDrafts) {
         if (frontMatter.draft && !includeDrafts) {
             continue;
         }
-        const relativePath = relative(contentDir, file);
+        // POSIX separators, so a page two folders deep gets /a/b/page on Windows too
+        const relativePath = relative(contentDir, file).replace(/\\/g, '/');
         const slug = computeSlug(relativePath);
         const url = computeUrl(slug, frontMatter);
         const page = {

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

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/core/dev.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAe,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAwC7D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAscD,wBAAsB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC,CA4hBxF"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/core/dev.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAe,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAoC7D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAmZD,wBAAsB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC,CAmhBxF"}

package/dist/core/dev.js

@@ -1,5 +1,4 @@
 import { createServer } from 'node:http';
-import { join, extname } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { WebSocketServer } from 'ws';
 import chokidar from 'chokidar';
@@ -8,10 +7,8 @@ import { invalidate } from './invalidate.js';
 import { loadConfig } from '../config/loader.js';
 import { clearTemplateEngineCache } from './templates.js';
 import { clearMarkdownProcessorCache } from './markdown.js';
-import { loadCacheManifest, saveCacheManifest, computeNavigationHash, DevServerLockManager, } from './isg/index.js';
-import { loadContent } from './content.js';
-import { buildNavigation } from './navigation.js';
-import { resolveDevPaths, resolveCacheDir, resolvePrettyUrl, createErrorOverlay, parseErrorDetails, TemplateError, createFallbackLogger, mergeServerOptions, createTypeScriptWatcher, isEnabledEnvFlag, refreshCssOutputWatcher, normalizePathForComparison, isPathWithinDirectory, assertPortAvailable, toPortUnavailableError, } from './utils/index.js';
+import { loadCacheManifest, saveCacheManifest, DevServerLockManager } from './isg/index.js';
+import { resolveDevPaths, resolveCacheDir, resolvePrettyUrl, resolveRequestFile, resolveNotFoundPage, getMimeType, parseRequestPath, createErrorOverlay, parseErrorDetails, TemplateError, createFallbackLogger, mergeServerOptions, createTypeScriptWatcher, isEnabledEnvFlag, refreshCssOutputWatcher, normalizePathForComparison, assertPortAvailable, toPortUnavailableError, } from './utils/index.js';
 import { setEnv, getEnv } from '../env.js';
 import { DEFAULT_DEV_PORT, DEFAULT_DEV_HOST, TEMPLATE_EXTENSION, DEFAULT_OUT_DIR, } from '../constants.js';
 /**
@@ -318,67 +315,18 @@ async function handleTemplateChange(templatePath, configPath, logger) {
     }
 }
 /**
- * Handles markdown file changes by comparing navigation hashes.
- * Only performs a full rebuild if navigation structure actually changed.
- * Navigation changes come from frontmatter modifications (title, order, description).
- * Content-only changes use incremental rebuilds.
+ * Handles markdown file changes (added, edited or deleted pages) with an incremental build.
+ * ISG decides what re-renders: the changed page, the pages that list it through a collection,
+ * and the pages that read the navigation when the change altered it. A deleted page's output
+ * is removed by the build.
  */
 async function handleMarkdownChange(_markdownPath, configPath, logger) {
-    const cacheDir = resolveCacheDir();
-    try {
-        // Load existing cache manifest
-        const cacheManifest = await loadCacheManifest(cacheDir);
-        if (!cacheManifest || !cacheManifest.navigationHash) {
-            // No cache or no navigation hash exists, perform full rebuild
-            await build({
-                logger,
-                force: false,
-                clean: false,
-                ...(configPath && { configPath }),
-            });
-            return;
-        }
-        // Load config and content to rebuild navigation tree
-        const config = await loadConfig(configPath);
-        const pages = await loadContent(config);
-        const newNavigation = buildNavigation(pages);
-        const newNavigationHash = computeNavigationHash(newNavigation);
-        // Compare navigation hashes
-        if (newNavigationHash !== cacheManifest.navigationHash) {
-            // Navigation structure changed - clear cache and force full rebuild
-            logger.status('Navigation structure changed, performing full rebuild...');
-            // Force rebuild bypasses ISG cache entirely
-            await build({
-                logger,
-                force: true, // Force rebuild to bypass cache
-                clean: false,
-                ...(configPath && { configPath }),
-            });
-        }
-        else {
-            // Navigation unchanged - use incremental rebuild for content changes
-            await build({
-                logger,
-                force: false,
-                clean: false,
-                ...(configPath && { configPath }),
-            });
-        }
-    }
-    catch (_error) {
-        try {
-            // Fallback to full rebuild
-            await build({
-                logger,
-                force: false,
-                clean: false,
-                ...(configPath && { configPath }),
-            });
-        }
-        catch (fallbackError) {
-            throw fallbackError instanceof Error ? fallbackError : new Error(String(fallbackError));
-        }
-    }
+    await build({
+        logger,
+        force: false,
+        clean: false,
+        ...(configPath && { configPath }),
+    });
 }
 export async function createDevServer(options = {}) {
     const logger = options.logger ?? createFallbackLogger();
@@ -418,30 +366,6 @@ export async function createDevServer(options = {}) {
     // Diagnostics toggles used for investigating dev-server rebuild slowdown.
     const disableCssWatcher = isEnabledEnvFlag(process.env.STATI_DEV_DISABLE_CSS_WATCHER);
     const disableWsReload = isEnabledEnvFlag(process.env.STATI_DEV_DISABLE_WS_RELOAD);
-    /**
-     * Gets MIME type for a file based on its extension
-     */
-    function getMimeType(filePath) {
-        const ext = extname(filePath).toLowerCase();
-        const mimeTypes = {
-            '.html': 'text/html',
-            '.js': 'application/javascript',
-            '.css': 'text/css',
-            '.json': 'application/json',
-            '.png': 'image/png',
-            '.jpg': 'image/jpeg',
-            '.jpeg': 'image/jpeg',
-            '.gif': 'image/gif',
-            '.svg': 'image/svg+xml',
-            '.ico': 'image/x-icon',
-            '.webp': 'image/webp',
-            '.woff': 'font/woff',
-            '.woff2': 'font/woff2',
-            '.ttf': 'font/ttf',
-            '.eot': 'application/vnd.ms-fontobject',
-        };
-        return mimeTypes[ext] || 'application/octet-stream';
-    }
     /**
      * Injects live reload script into HTML responses
      */
@@ -512,9 +436,9 @@ export async function createDevServer(options = {}) {
                 statusCode: 500,
             };
         }
-        const originalFilePath = join(outDir, requestPath === '/' ? 'index.html' : requestPath);
-        // Security: Prevent path traversal attacks
-        if (!isPathWithinDirectory(outDir, originalFilePath)) {
+        // Security: the file the request names, or null when it is outside the output directory
+        const requestFile = resolveRequestFile(outDir, requestPath);
+        if (requestFile === null) {
             return {
                 content: '403 - Forbidden',
                 mimeType: 'text/plain',
@@ -522,7 +446,7 @@ export async function createDevServer(options = {}) {
             };
         }
         // Use the shared pretty URL resolver
-        const { filePath, found } = await resolvePrettyUrl(outDir, requestPath, originalFilePath);
+        const { filePath, found } = await resolvePrettyUrl(outDir, requestPath, requestFile);
         if (!found || !filePath) {
             // If we have a build error and this is an HTML request, show error overlay instead of 404
             const errorToShow = lastBuildError;
@@ -559,6 +483,16 @@ export async function createDevServer(options = {}) {
                     statusCode: 500,
                 };
             }
+            // Serve the site's 404 page, as static hosts do, with live reload so it updates on edits
+            const notFoundPage = await resolveNotFoundPage(outDir);
+            if (notFoundPage) {
+                const html = await readFile(notFoundPage, 'utf-8');
+                return {
+                    content: injectLiveReloadScript(html),
+                    mimeType: 'text/html',
+                    statusCode: 404,
+                };
+            }
             return {
                 content: requestPath.endsWith('/')
                     ? '404 - Directory listing not available'
@@ -652,12 +586,17 @@ export async function createDevServer(options = {}) {
             await performInitialBuild(configPath, logger, setLastBuildError);
             // Create HTTP server
             httpServer = createServer(async (req, res) => {
-                const requestPath = req.url || '/';
+                const requestPath = parseRequestPath(req.url);
                 const requestStart = Date.now();
                 // Handle WebSocket upgrade path
                 if (requestPath === '/__ws') {
                     return; // Let WebSocket server handle this
                 }
+                if (requestPath === null) {
+                    res.writeHead(400, { 'Content-Type': 'text/plain' });
+                    res.end('400 - Bad Request');
+                    return;
+                }
                 // Only log page requests, not static assets (files with extensions)
                 const hasFileExtension = requestPath.includes('.') && !requestPath.endsWith('.html');
                 if (!hasFileExtension) {

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"}