@stati/core 1.16.3 → 1.18.0

package/dist/core/build.d.ts

@@ -1,7 +1,22 @@
 import type { BuildStats, Logger } from '../types/index.js';
+import type { BuildMetrics } from '../metrics/index.js';
+/**
+ * Options for metrics collection during builds.
+ */
+export interface MetricsOptions {
+    /** Enable metrics collection */
+    enabled?: boolean;
+    /** Include per-page timing details */
+    detailed?: boolean;
+}
 /**
  * Options for customizing the build process.
  *
+ * @remarks
+ * The `| undefined` on optional properties is intentional due to
+ * `exactOptionalPropertyTypes: true` in tsconfig.json, allowing callers
+ * to explicitly pass `undefined` values.
+ *
  * @example
  * ```typescript
  * const options: BuildOptions = {
@@ -9,23 +24,33 @@ import type { BuildStats, Logger } from '../types/index.js';
  *   clean: true,        // Clean output directory before build
  *   configPath: './custom.config.js',  // Custom config file path
  *   includeDrafts: true, // Include draft pages in build
- *   version: '1.0.0'    // Version to display in build messages
+ *   version: '1.0.0',   // Version to display in build messages
+ *   metrics: { enabled: true, detailed: true }  // Enable metrics collection
  * };
  * ```
  */
 export interface BuildOptions {
     /** Force rebuild of all pages, ignoring cache */
-    force?: boolean;
+    force?: boolean | undefined;
     /** Clean the output directory before building */
-    clean?: boolean;
+    clean?: boolean | undefined;
     /** Path to a custom configuration file */
-    configPath?: string;
+    configPath?: string | undefined;
     /** Include draft pages in the build */
-    includeDrafts?: boolean;
+    includeDrafts?: boolean | undefined;
     /** Custom logger for build output */
-    logger?: Logger;
+    logger?: Logger | undefined;
     /** Version information to display in build messages */
-    version?: string;
+    version?: string | undefined;
+    /** Metrics collection options */
+    metrics?: MetricsOptions | undefined;
+}
+/**
+ * Extended build result including optional metrics.
+ */
+export interface BuildResult extends BuildStats {
+    /** Build metrics (only present when metrics enabled) */
+    buildMetrics?: BuildMetrics;
 }
 /**
  * Builds the Stati site with ISG support.
@@ -43,20 +68,24 @@ export interface BuildOptions {
  * 5. Update cache manifest
  *
  * @param options - Build configuration options
- * @returns Promise resolving to build statistics
+ * @returns Promise resolving to build result with statistics and optional metrics
  * @throws {Error} When configuration is invalid
  * @throws {Error} When template rendering fails
  * @throws {Error} When build lock cannot be acquired
  *
  * @example
  * ```typescript
- * const stats = await build({
+ * const result = await build({
  *   force: true,
  *   clean: true,
- *   includeDrafts: false
+ *   includeDrafts: false,
+ *   metrics: { enabled: true }
  * });
- * console.log(`Built ${stats.pageCount} pages in ${stats.buildTime}ms`);
+ * console.log(`Built ${result.totalPages} pages in ${result.buildTimeMs}ms`);
+ * if (result.buildMetrics) {
+ *   console.log(`Cache hit rate: ${result.buildMetrics.isg.cacheHitRate}`);
+ * }
  * ```
  */
-export declare function build(options?: BuildOptions): Promise<BuildStats>;
+export declare function build(options?: BuildOptions): Promise<BuildResult>;
 //# sourceMappingURL=build.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/core/build.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EAEV,UAAU,EACV,MAAM,EAMP,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA4FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAW3E"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/core/build.ts"],"names":[],"mappings":"AAgDA,OAAO,KAAK,EAEV,UAAU,EACV,MAAM,EAMP,MAAM,mBAAmB,CAAC;AAC3B,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,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,iCAAiC;IACjC,OAAO,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AA4FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAW5E"}

package/dist/core/build.js

@@ -1,5 +1,6 @@
 import { ensureDir, writeFile, remove, pathExists, stat, readdir, copyFile, resolveOutDir, resolveStaticDir, resolveCacheDir, enableInventoryTracking, disableInventoryTracking, clearInventory, writeTailwindClassInventory, getInventorySize, isTailwindUsed, loadPreviousInventory, compileTypeScript, autoInjectBundles, getBundlePathsForPage, } 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 { createMarkdownProcessor, renderMarkdown } from './markdown.js';
@@ -10,6 +11,7 @@ import { generateSitemap, generateRobotsTxtFromConfig, autoInjectSEO, } from '..
 import { generateRSSFeeds, validateRSSConfig } from '../rss/index.js';
 import { getEnv } from '../env.js';
 import { DEFAULT_OUT_DIR } from '../constants.js';
+import { createMetricRecorder, noopMetricRecorder } from '../metrics/index.js';
 /**
  * Recursively calculates the total size of a directory in bytes.
  * Used for build statistics.
@@ -103,19 +105,23 @@ const defaultLogger = {
  * 5. Update cache manifest
  *
  * @param options - Build configuration options
- * @returns Promise resolving to build statistics
+ * @returns Promise resolving to build result with statistics and optional metrics
  * @throws {Error} When configuration is invalid
  * @throws {Error} When template rendering fails
  * @throws {Error} When build lock cannot be acquired
  *
  * @example
  * ```typescript
- * const stats = await build({
+ * const result = await build({
  *   force: true,
  *   clean: true,
- *   includeDrafts: false
+ *   includeDrafts: false,
+ *   metrics: { enabled: true }
  * });
- * console.log(`Built ${stats.pageCount} pages in ${stats.buildTime}ms`);
+ * console.log(`Built ${result.totalPages} pages in ${result.buildTimeMs}ms`);
+ * if (result.buildMetrics) {
+ *   console.log(`Cache hit rate: ${result.buildMetrics.isg.cacheHitRate}`);
+ * }
  * ```
  */
 export async function build(options = {}) {
@@ -184,14 +190,16 @@ async function loadContentAndBuildNavigation(config, options, logger) {
 /**
  * Processes pages with ISG caching logic.
  */
-async function processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles) {
+async function processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder = noopMetricRecorder) {
     let cacheHits = 0;
     let cacheMisses = 0;
     // Build context
     const buildContext = { config, pages };
     // Run beforeAll hook
     if (config.hooks?.beforeAll) {
+        const endHookBeforeAll = recorder.startSpan('hookBeforeAllMs');
         await config.hooks.beforeAll(buildContext);
+        endHookBeforeAll();
     }
     // Render each page with tree-based progress tracking and ISG
     if (logger.step) {
@@ -239,22 +247,30 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
             else {
                 logger.processing(`📋 Cached ${page.url}`);
             }
+            // Record page timing for cached pages (0ms render time)
+            recorder.recordPageTiming(page.url, 0, true);
             continue;
         }
         // Cache miss - need to rebuild
         cacheMisses++;
-        const startTime = Date.now();
+        const startTime = performance.now();
         // Run beforeRender hook
         if (config.hooks?.beforeRender) {
+            const hookStart = performance.now();
             await config.hooks.beforeRender({ page, config });
+            recorder.addToPhase('hookBeforeRenderTotalMs', performance.now() - hookStart);
         }
-        // Render markdown to HTML
-        const htmlContent = renderMarkdown(page.content, md);
+        // Render markdown to HTML with TOC extraction
+        const tocEnabled = config.markdown?.toc !== false;
+        const { html: htmlContent, toc } = renderMarkdown(page.content, md, tocEnabled);
         // Compute matched bundle paths for this page
         const bundlePaths = getBundlePathsForPage(page.url, compiledBundles);
         const assets = bundlePaths.length > 0 ? { bundlePaths } : undefined;
         // Render with template
-        let finalHtml = await renderPage(page, htmlContent, config, eta, navigation, pages, assets);
+        const renderResult = await renderPage(page, htmlContent, config, eta, navigation, pages, assets, toc, logger);
+        let finalHtml = renderResult.html;
+        // Record templates loaded for this page
+        recorder.increment('templatesLoaded', renderResult.templatesLoaded);
         // Auto-inject SEO tags if enabled
         if (config.seo?.autoInject !== false) {
             const injectOptions = {
@@ -273,7 +289,9 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         if (shouldAutoInject && assets && assets.bundlePaths.length > 0) {
             finalHtml = autoInjectBundles(finalHtml, assets.bundlePaths);
         }
-        const renderTime = Date.now() - startTime;
+        const renderTime = Math.round(performance.now() - startTime);
+        // Record page timing for rendered pages (includes template count)
+        recorder.recordPageTiming(page.url, renderTime, false, renderResult.templatesLoaded);
         if (logger.updateTreeNode) {
             logger.updateTreeNode(pageId, 'completed', {
                 timing: renderTime,
@@ -292,7 +310,9 @@ async function processPagesWithCache(pages, manifest, config, outDir, md, eta, n
         }
         // Run afterRender hook
         if (config.hooks?.afterRender) {
+            const hookStart = performance.now();
             await config.hooks.afterRender({ page, config });
+            recorder.addToPhase('hookAfterRenderTotalMs', performance.now() - hookStart);
         }
     }
     // Display final rendering tree and clear it
@@ -347,11 +367,29 @@ async function generateBuildStats(pages, assetsCount, buildStartTime, outDir, ca
  * Separated for cleaner error handling and testing.
  */
 async function buildInternal(options = {}) {
+    // Date.now() is used for user-facing build duration display (wall-clock time, in milliseconds).
+    // Note: Date.now() can be affected by system clock changes and is not monotonic.
+    // Internal metrics use performance.now() via the MetricRecorder for higher precision and monotonic timing,
+    // which is not affected by system clock adjustments.
     const buildStartTime = Date.now();
     const logger = options.logger || defaultLogger;
+    // Create metric recorder (noop if disabled)
+    const recorder = createMetricRecorder({
+        enabled: options.metrics?.enabled,
+        detailed: options.metrics?.detailed,
+        command: 'build',
+        flags: {
+            force: options.force,
+            clean: options.clean,
+            includeDrafts: options.includeDrafts,
+        },
+        statiVersion: options.version,
+    });
     logger.building('Building your site...');
-    // Load configuration
+    // Load configuration (instrumented)
+    const endConfigSpan = recorder.startSpan('configLoadMs');
     const { config, outDir, cacheDir } = await loadAndValidateConfig(options);
+    endConfigSpan();
     // Initialize cache stats
     let cacheHits = 0;
     let cacheMisses = 0;
@@ -384,17 +422,27 @@ async function buildInternal(options = {}) {
         }
     }
     // Load cache manifest for ISG (after potential clean operation)
+    const endManifestLoadSpan = recorder.startSpan('cacheManifestLoadMs');
     const { manifest } = await setupCacheAndManifest(cacheDir);
+    endManifestLoadSpan();
     // Load content and build navigation
     if (logger.step) {
         console.log(); // Add spacing before content loading
     }
+    const endContentSpan = recorder.startSpan('contentDiscoveryMs');
     const { pages, 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.
+    recorder.increment('totalPages', pages.length);
+    recorder.increment('markdownFilesProcessed', pages.length);
     // Store navigation hash in manifest for change detection in dev server
     manifest.navigationHash = navigationHash;
     // Compile TypeScript if enabled
     let compiledBundles = [];
     if (config.typescript?.enabled) {
+        const endTsSpan = recorder.startSpan('typescriptCompileMs');
         compiledBundles = await compileTypeScript({
             projectRoot: process.cwd(),
             config: config.typescript,
@@ -402,15 +450,21 @@ async function buildInternal(options = {}) {
             mode: getEnv() === 'production' ? 'production' : 'development',
             logger,
         });
+        endTsSpan();
     }
     // Process pages with ISG caching logic
     if (logger.step) {
         console.log(); // Add spacing before page processing
     }
+    const endPageRenderSpan = recorder.startSpan('pageRenderingMs');
     const buildTime = new Date();
-    const pageProcessingResult = await processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles);
+    const pageProcessingResult = await processPagesWithCache(pages, manifest, config, outDir, md, eta, navigation, buildTime, options, logger, compiledBundles, recorder);
+    endPageRenderSpan();
     cacheHits = pageProcessingResult.cacheHits;
     cacheMisses = pageProcessingResult.cacheMisses;
+    // Record page rendering counts
+    recorder.increment('renderedPages', cacheMisses);
+    recorder.increment('cachedPages', cacheHits);
     // Write Tailwind class inventory after all templates have been rendered (if Tailwind is used)
     if (hasTailwind) {
         const inventorySize = getInventorySize();
@@ -423,10 +477,15 @@ async function buildInternal(options = {}) {
         disableInventoryTracking();
     }
     // Save updated cache manifest
+    const endManifestSaveSpan = recorder.startSpan('cacheManifestSaveMs');
     await saveCacheManifest(cacheDir, manifest);
+    endManifestSaveSpan();
     // Copy static assets and count them
+    const endAssetSpan = recorder.startSpan('assetCopyMs');
     let assetsCount = 0;
     assetsCount = await copyStaticAssets(config, outDir, logger);
+    endAssetSpan();
+    recorder.increment('assetsCopied', assetsCount);
     // Get current environment
     const currentEnv = getEnv();
     // Generate sitemap if enabled (only in production mode)
@@ -435,8 +494,10 @@ async function buildInternal(options = {}) {
             console.log(); // Add spacing before sitemap generation
         }
         logger.info('Generating sitemap...');
+        const endSitemapSpan = recorder.startSpan('sitemapGenerationMs');
         const sitemapResult = generateSitemap(pages, config, config.sitemap);
         await writeFile(join(outDir, 'sitemap.xml'), sitemapResult.xml);
+        endSitemapSpan();
         // Write additional sitemap files if split
         if (sitemapResult.sitemaps) {
             for (const { filename, xml } of sitemapResult.sitemaps) {
@@ -506,9 +567,30 @@ async function buildInternal(options = {}) {
     }
     // Run afterAll hook
     if (config.hooks?.afterAll) {
+        const endHookAfterAll = recorder.startSpan('hookAfterAllMs');
         await config.hooks.afterAll({ config, pages });
+        endHookAfterAll();
     }
     // Calculate build statistics
     const buildStats = await generateBuildStats(pages, assetsCount, buildStartTime, outDir, cacheHits, cacheMisses, logger);
-    return buildStats;
+    // Set ISG metrics
+    const totalPages = pages.length;
+    const cacheHitRate = totalPages > 0 ? cacheHits / totalPages : 0;
+    recorder.setISGMetrics({
+        enabled: config.isg?.enabled !== false,
+        cacheHitRate,
+        manifestEntries: Object.keys(manifest.entries).length,
+        invalidatedEntries: cacheMisses,
+    });
+    // Take final memory snapshot
+    recorder.snapshotMemory();
+    // Build result with optional metrics
+    const result = {
+        ...buildStats,
+    };
+    // Add metrics if enabled
+    if (recorder.enabled) {
+        result.buildMetrics = recorder.finalize();
+    }
+    return result;
 }

package/dist/core/index.d.ts

@@ -3,7 +3,7 @@
  * Barrel file for all core Stati functionality including build, dev server, preview, and invalidation.
  */
 export { build } from './build.js';
-export type { BuildOptions } from './build.js';
+export type { BuildOptions, MetricsOptions, BuildResult } from './build.js';
 export { createDevServer } from './dev.js';
 export type { DevServerOptions } from './dev.js';
 export { createPreviewServer } from './preview.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG5E,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/core/markdown.d.ts

@@ -1,9 +1,26 @@
 import MarkdownIt from 'markdown-it';
-import type { StatiConfig } from '../types/index.js';
+import type { StatiConfig, TocEntry } from '../types/index.js';
+/**
+ * Result of rendering markdown content.
+ */
+export interface MarkdownResult {
+    /** The rendered HTML content */
+    html: string;
+    /** Table of contents entries extracted from headings */
+    toc: TocEntry[];
+}
 /**
  * Creates and configures a MarkdownIt processor based on the provided configuration.
  * Supports both plugin array format and configure function format.
  */
 export declare function createMarkdownProcessor(config: StatiConfig): Promise<MarkdownIt>;
-export declare function renderMarkdown(content: string, md: MarkdownIt): string;
+/**
+ * Renders markdown content to HTML with optional TOC extraction.
+ *
+ * @param content - The markdown content to render
+ * @param md - The configured MarkdownIt instance
+ * @param tocEnabled - Whether to extract TOC and inject heading anchors (default: true)
+ * @returns Object containing rendered HTML and TOC entries
+ */
+export declare function renderMarkdown(content: string, md: MarkdownIt, tocEnabled?: boolean): MarkdownResult;
 //# sourceMappingURL=markdown.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/core/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,aAAa,CAAC;AAIrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAmBrD;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAuCtF;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,MAAM,CAEtE"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/core/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,aAAa,CAAC;AAKrC,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,GAAG,EAAE,QAAQ,EAAE,CAAC;CACjB;AAmBD;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAuCtF;AA6ED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,UAAU,EACd,UAAU,GAAE,OAAc,GACzB,cAAc,CAWhB"}

package/dist/core/markdown.js

@@ -2,6 +2,7 @@ import MarkdownIt from 'markdown-it';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import path from 'node:path';
+import { slugify } from './utils/index.js';
 /**
  * Load a markdown plugin, trying different resolution strategies
  */
@@ -62,6 +63,84 @@ export async function createMarkdownProcessor(config) {
     }
     return md;
 }
-export function renderMarkdown(content, md) {
-    return md.render(content);
+/**
+ * Extracts text content from an inline token, handling nested children.
+ * Recursively processes all token types to capture text from links, images,
+ * code, and other inline elements.
+ *
+ * @param token - The inline token to extract text from
+ * @returns Plain text content
+ */
+function extractTextFromToken(token) {
+    // Handle tokens with children by recursively extracting from all children
+    if (token.children && token.children.length > 0) {
+        return token.children.map((child) => extractTextFromToken(child)).join('');
+    }
+    // For leaf tokens, return their content
+    // This handles 'text', 'code_inline', and other inline token types
+    return token.content || '';
+}
+/**
+ * Extracts TOC entries from tokens and injects anchor IDs into heading tokens.
+ *
+ * @param tokens - The parsed markdown tokens
+ * @param tocEnabled - Whether TOC extraction is enabled
+ * @returns Array of TOC entries
+ */
+function extractAndInjectAnchors(tokens, tocEnabled) {
+    if (!tocEnabled) {
+        return [];
+    }
+    const toc = [];
+    const usedIds = new Map();
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (!token)
+            continue;
+        if (token.type === 'heading_open') {
+            // Extract level from tag (h1, h2, etc.)
+            const level = parseInt(token.tag.slice(1), 10);
+            // Only include levels 2-6 in TOC (skip h1)
+            if (level >= 2 && level <= 6) {
+                // Get the inline token that follows (contains heading text)
+                const inlineToken = tokens[i + 1];
+                if (inlineToken && inlineToken.type === 'inline') {
+                    const text = extractTextFromToken(inlineToken);
+                    let baseId = slugify(text);
+                    // Fallback for empty slugs (e.g., headings with only emojis or special characters)
+                    if (!baseId) {
+                        baseId = 'heading';
+                    }
+                    // Handle duplicate IDs
+                    let id = baseId;
+                    const count = usedIds.get(baseId) || 0;
+                    if (count > 0) {
+                        id = `${baseId}-${count}`;
+                    }
+                    usedIds.set(baseId, count + 1);
+                    // Inject the id attribute into the heading_open token
+                    token.attrSet('id', id);
+                    toc.push({ id, text, level });
+                }
+            }
+        }
+    }
+    return toc;
+}
+/**
+ * Renders markdown content to HTML with optional TOC extraction.
+ *
+ * @param content - The markdown content to render
+ * @param md - The configured MarkdownIt instance
+ * @param tocEnabled - Whether to extract TOC and inject heading anchors (default: true)
+ * @returns Object containing rendered HTML and TOC entries
+ */
+export function renderMarkdown(content, md, tocEnabled = true) {
+    // Parse content into tokens
+    const tokens = md.parse(content, {});
+    // Extract TOC and inject anchor IDs
+    const toc = extractAndInjectAnchors(tokens, tocEnabled);
+    // Render tokens to HTML
+    const html = md.renderer.render(tokens, md.options, {});
+    return { html, toc };
 }

package/dist/core/templates.d.ts

@@ -1,5 +1,14 @@
 import { Eta } from 'eta';
-import type { StatiConfig, PageModel, NavNode } from '../types/index.js';
+import type { StatiConfig, PageModel, NavNode, TocEntry, Logger } from '../types/index.js';
+/**
+ * Result of rendering a page template.
+ */
+export interface RenderResult {
+    /** The rendered HTML content */
+    html: string;
+    /** Number of templates loaded (layout + partials) */
+    templatesLoaded: number;
+}
 export declare function createTemplateEngine(config: StatiConfig): Eta;
-export declare function renderPage(page: PageModel, body: string, config: StatiConfig, eta: Eta, navigation?: NavNode[], allPages?: PageModel[], assets?: import('../types/index.js').StatiAssets): Promise<string>;
+export declare function renderPage(page: PageModel, body: string, config: StatiConfig, eta: Eta, navigation?: NavNode[], allPages?: PageModel[], assets?: import('../types/index.js').StatiAssets, toc?: TocEntry[], logger?: Logger): Promise<RenderResult>;
 //# sourceMappingURL=templates.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/core/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAG1B,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAkB,MAAM,mBAAmB,CAAC;AAmNzF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,GAAG,CAW7D;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,GAAG,EACR,UAAU,CAAC,EAAE,OAAO,EAAE,EACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,EACtB,MAAM,CAAC,EAAE,OAAO,mBAAmB,EAAE,WAAW,GAC/C,OAAO,CAAC,MAAM,CAAC,CA+KjB"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/core/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAG1B,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,OAAO,EAEP,QAAQ,EACR,MAAM,EACP,MAAM,mBAAmB,CAAC;AAkB3B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC;CACzB;AAoMD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,GAAG,CAW7D;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,GAAG,EACR,UAAU,CAAC,EAAE,OAAO,EAAE,EACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,EACtB,MAAM,CAAC,EAAE,OAAO,mBAAmB,EAAE,WAAW,EAChD,GAAG,CAAC,EAAE,QAAQ,EAAE,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CAuMvB"}

package/dist/core/templates.js

@@ -1,6 +1,7 @@
 import { Eta } from 'eta';
 import { join, dirname, relative, basename, posix } from 'node:path';
 import glob from 'fast-glob';
+import { createFallbackLogger } from './utils/index.js';
 import { TEMPLATE_EXTENSION } from '../constants.js';
 import { getStatiVersion, isCollectionIndexPage, discoverLayout, getCollectionPathForPage, resolveSrcDir, createTemplateError, createValidatingPartialsProxy, propValue, wrapPartialsAsCallable, createNavigationHelpers, } from './utils/index.js';
 import { getEnv } from '../env.js';
@@ -182,11 +183,14 @@ export function createTemplateEngine(config) {
     });
     return eta;
 }
-export async function renderPage(page, body, config, eta, navigation, allPages, assets) {
+export async function renderPage(page, body, config, eta, navigation, allPages, assets, toc, logger) {
+    const log = logger || createFallbackLogger();
     // Discover partials for this page's directory hierarchy
     const srcDir = resolveSrcDir(config);
     const relativePath = relative(srcDir, page.sourcePath);
     const partialPaths = await discoverPartials(relativePath, config);
+    // Count templates: partials + layout (if found)
+    const partialsCount = Object.keys(partialPaths).length;
     // Build collection data based on page type
     let collectionData;
     const isIndexPage = allPages && isCollectionIndexPage(page, allPages);
@@ -203,19 +207,31 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
     // Discover the appropriate layout using hierarchical layout.eta convention
     // Pass isIndexPage flag to enable index.eta lookup for aggregation pages
     const layoutPath = await discoverLayout(relativePath, config, page.frontMatter.layout, isIndexPage);
+    // Calculate total templates loaded (partials + layout if present)
+    const templatesLoaded = partialsCount + (layoutPath ? 1 : 0);
     // Create navigation helpers
     const navTree = navigation || [];
     const navHelpers = createNavigationHelpers(navTree, page);
     const currentNavNode = navHelpers.getCurrentNode();
+    // Define page-specific properties that override frontmatter
+    const pageOverrides = {
+        path: page.url,
+        url: page.url, // Add url property for compatibility
+        content: body,
+        navNode: currentNavNode, // Add current page's navigation node
+        toc: toc || [], // Table of contents entries extracted from markdown headings
+    };
+    // Check for frontmatter keys that conflict with reserved page properties
+    const conflictingKeys = Object.keys(pageOverrides).filter((key) => key in page.frontMatter);
+    if (conflictingKeys.length > 0) {
+        log.warning(`Frontmatter in "${page.sourcePath}" contains reserved keys that will be overwritten: ${conflictingKeys.join(', ')}`);
+    }
     // Create base context for partial rendering
     const baseContext = {
         site: config.site,
         page: {
             ...page.frontMatter,
-            path: page.url,
-            url: page.url, // Add url property for compatibility
-            content: body,
-            navNode: currentNavNode, // Add current page's navigation node
+            ...pageOverrides,
         },
         content: body,
         nav: navHelpers, // Replace navigation with nav helpers
@@ -260,7 +276,7 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
             catch (error) {
                 // If this is the last pass, log the error and create placeholder
                 if (pass === maxPasses - 1) {
-                    console.warn(`Warning: Failed to render partial ${partialName} at ${partialPath}:`, error);
+                    log.warning(`Failed to render partial ${partialName} at ${partialPath}: ${error instanceof Error ? error.message : String(error)}`);
                     // In development mode, throw enhanced template error for partials too
                     if (getEnv() === 'development') {
                         const templateError = createTemplateError(error instanceof Error ? error : new Error(String(error)), partialPath);
@@ -302,19 +318,20 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
     };
     try {
         if (!layoutPath) {
-            console.warn('No layout template found, using fallback');
-            return createFallbackHtml(page, body);
+            log.warning('No layout template found, using fallback');
+            return { html: createFallbackHtml(page, body), templatesLoaded };
         }
-        return await eta.renderAsync(layoutPath, context);
+        const html = await eta.renderAsync(layoutPath, context);
+        return { html, templatesLoaded };
     }
     catch (error) {
-        console.error(`Error rendering layout ${layoutPath || 'unknown'}:`, error);
+        log.error(`Error rendering layout ${layoutPath || 'unknown'}: ${error instanceof Error ? error.message : String(error)}`);
         // In development mode, throw enhanced template error for better debugging
         if (getEnv() === 'development') {
             const templateError = createTemplateError(error instanceof Error ? error : new Error(String(error)), layoutPath || undefined);
             throw templateError;
         }
-        return createFallbackHtml(page, body);
+        return { html: createFallbackHtml(page, body), templatesLoaded };
     }
 }
 function createFallbackHtml(page, body) {

package/dist/core/utils/index.d.ts

@@ -6,6 +6,7 @@ export { readFile, writeFile, pathExists, ensureDir, remove, copyFile, readdir,
 export { resolveSrcDir, resolveOutDir, resolveStaticDir, resolveCacheDir, resolveDevPaths, normalizeTemplatePath, resolveSrcPath, resolveOutPath, resolveStaticPath, } from './paths.utils.js';
 export { discoverLayout, isCollectionIndexPage, getCollectionPathForPage, } from './template-discovery.utils.js';
 export { propValue } from './template.utils.js';
+export { slugify } from './slugify.utils.js';
 export { trackTailwindClass, enableInventoryTracking, disableInventoryTracking, clearInventory, getInventory, getInventorySize, isTrackingEnabled, writeTailwindClassInventory, isTailwindUsed, resetTailwindDetection, loadPreviousInventory, } from './tailwind-inventory.utils.js';
 export { createValidatingPartialsProxy } from './partial-validation.utils.js';
 export { makeCallablePartial, wrapPartialsAsCallable } from './callable-partials.utils.js';

package/dist/core/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,UAAU,EACV,SAAS,EACT,MAAM,EACN,QAAQ,EACR,OAAO,EACP,IAAI,GACL,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,EAC3B,cAAc,EACd,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAG9E,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,YAAY,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAG/F,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACjF,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,UAAU,EACV,SAAS,EACT,MAAM,EACN,QAAQ,EACR,OAAO,EACP,IAAI,GACL,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,EAC3B,cAAc,EACd,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAG9E,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,YAAY,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAG/F,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACjF,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/core/utils/index.js

@@ -10,6 +10,8 @@ export { resolveSrcDir, resolveOutDir, resolveStaticDir, resolveCacheDir, resolv
 export { discoverLayout, isCollectionIndexPage, getCollectionPathForPage, } from './template-discovery.utils.js';
 // Template utilities
 export { propValue } from './template.utils.js';
+// Slugify utilities
+export { slugify } from './slugify.utils.js';
 // Tailwind inventory utilities
 export { trackTailwindClass, enableInventoryTracking, disableInventoryTracking, clearInventory, getInventory, getInventorySize, isTrackingEnabled, writeTailwindClassInventory, isTailwindUsed, resetTailwindDetection, loadPreviousInventory, } from './tailwind-inventory.utils.js';
 // Partial validation utilities