@zeropress/build-pages 0.6.3 → 0.6.4

package/README.md

@@ -19,7 +19,7 @@ public directory
         |
         v
 @zeropress/build-pages
-  generates .zeropress/preview-data.json
+  generates .zeropress-build-page/preview-data.json
   stages public files
         |
         v
@@ -40,7 +40,7 @@ flowchart TD
   config --> buildPages
   publicFiles --> buildPages
 
-  buildPages --> previewData[".zeropress/preview-data.json<br/>internal generated build input"]
+  buildPages --> previewData[".zeropress-build-page/preview-data.json<br/>internal generated build input"]
   buildPages --> stagedPublic["Staged public files"]
 
   previewData --> build["@zeropress/build"]
@@ -154,7 +154,7 @@ In the action inputs:
 - `source` is the directory that contains your Markdown pages and optional `.zeropress/config.json`. The default is `./docs`.
 - `public-dir` is the directory copied as public passthrough files. The default is `source`. If you set it explicitly, the directory must exist.
 - `destination` is the directory where the generated static site is written. The default is `./_site`.
-- `theme` is the bundled theme name. The default is `docs`.
+- `theme` is the bundled theme name. The default is `docs`; `docs1` is an alias for `docs`.
 - `theme-path` is a custom local ZeroPress theme directory. It takes precedence over `theme`.
 - `config` is the config file path. The default is `<source>/.zeropress/config.json`.
 - `site-url` overrides the canonical site URL from config.
@@ -235,7 +235,7 @@ The CLI requires explicit input and output paths. The GitHub Action keeps safe d
 | `--source <dir>` | required | Dedicated source directory containing Markdown and optional config |
 | `--public-dir <dir>` | source | Public passthrough directory. Explicit paths must exist. |
 | `--destination <dir>` | required | Output directory |
-| `--theme <name>` | `docs` | Bundled theme name |
+| `--theme <name>` | `docs` | Bundled theme name. `docs1` aliases `docs`. |
 | `--theme-path <dir>` | none | Custom ZeroPress theme directory |
 | `--config <path>` | `<source>/.zeropress/config.json` | Build Pages config |
 | `--site-url <url>` | config `site.url` | Canonical URL override |
@@ -270,7 +270,7 @@ Root-level public files named `favicon.ico`, `favicon.svg`, `favicon.png`, and `
 
 A root-level public `sitemap.xsl` is copied to the destination. When ZeroPress generates `sitemap.xml`, it auto-discovers that file and adds an XML stylesheet processing instruction for `/sitemap.xsl`.
 
-The source directory must not overlap the destination directory, the selected theme directory, or the internal `.zeropress/` working directory. An explicit public directory must be an existing dedicated directory and must not be a file, symlink, repository root, destination directory, selected theme directory, or internal `.zeropress/` working directory.
+The source directory must not overlap the destination directory, the selected theme directory, or the internal `.zeropress-build-page/` working directory. An explicit public directory must be an existing dedicated directory and must not be a file, symlink, repository root, destination directory, selected theme directory, or internal `.zeropress-build-page/` working directory.
 
 If `public-dir` is inside `source`, Build Pages excludes that public subtree from Markdown page discovery.
 
@@ -312,6 +312,7 @@ description: Build a static docs site from Markdown.
 path: guides/install
 status: published
 discoverability: default
+last_updated: none
 meta:
   source: docs
 data:
@@ -337,6 +338,7 @@ Supported front matter fields:
 | `path` | Generated route path, such as `guides/install` for `/guides/install`. |
 | `status` | `published` includes the page. `draft` skips the page. Other values warn and skip. |
 | `discoverability` | `default`, `noindex`, or `delist`. Missing is `default`. |
+| `last_updated` | `none` or `git`. Overrides config `markdown.last_updated` for this page. |
 | `meta` | Optional scalar/null metadata copied to the generated page. |
 | `data` | Optional structured JSON-style data for theme-facing lists, facts, galleries, timelines, or swatches. |
 
@@ -352,6 +354,8 @@ Unknown front matter fields are ignored to make migration from existing Markdown
 
 `delist` is not a security or permission feature. Direct links, explicit menus, explicit collections, and body links can still expose the page.
 
+`last_updated` controls optional Git-based page metadata. If config uses `markdown.last_updated: "git"`, set `last_updated: none` on landing, index, or promotional pages that should not show an update date. If config uses `none`, set `last_updated: git` on a specific information page to opt in.
+
 Use `meta` for small scalar flags and metadata. Use `data` when a theme should iterate structured content:
 
 ```html
@@ -411,7 +415,7 @@ progressive enhancement owned by the theme or site.
 
 Build Pages reads `<source>/.zeropress/config.json` when present. Missing config falls back to defaults.
 
-See the public config reference at [zeropress.dev/build-pages-config](https://zeropress.dev/build-pages-config/).
+See the public config reference at [zeropress.dev/build-pages-config](https://zeropress.dev/build-pages/config/).
 
 ```json
 {
@@ -438,6 +442,9 @@ See the public config reference at [zeropress.dev/build-pages-config](https://ze
       "show_sponsor_banner": false
     }
   },
+  "markdown": {
+    "last_updated": "git"
+  },
   "front_page": {
     "type": "markdown"
   },
@@ -457,6 +464,15 @@ See the public config reference at [zeropress.dev/build-pages-config](https://ze
       ]
     }
   },
+  "collections": {
+    "guides": {
+      "title": "Guides",
+      "items": [
+        "getting-started/index.md",
+        "deployment/index.md"
+      ]
+    }
+  },
   "custom_html": {
     "head_end": { "file": ".zeropress/head-end.html" },
     "body_end": { "file": ".zeropress/body-end.html" }
@@ -475,6 +491,22 @@ HTML front page and `custom_html` files must stay inside `.zeropress/`.
 
 Menu item `meta` is optional scalar display metadata copied into generated preview-data for themes that manually iterate menus. Use it for small values such as `icon`, `badge`, or `accent`; arrays and objects are not accepted.
 
+`collections` defines group-level reading order from Markdown source paths. Build Pages converts each source-relative `.md` path into preview-data collection items such as `{ "type": "page", "slug": "deployment" }`. Collection prev/next cursors stop at collection boundaries, so the last item in `collections.guides` does not continue into another collection.
+
+`markdown.last_updated` is optional and accepts `none` or `git`. Missing or `none` keeps current behavior and generates no update date. `git` reads each Markdown file's latest Git commit date and adds `page.meta.last_updated_iso` plus `page.meta.last_updated` to generated preview-data when the page does not already define those meta keys. `last_updated_iso` keeps the Git ISO timestamp; `last_updated` is a stable `YYYY-MM-DD` fallback display string. For accurate history in GitHub Actions, configure checkout with `fetch-depth: 0`.
+
+Themes can render the generated value with normal escaped interpolation:
+
+```html
+{{#if page.meta.last_updated_iso}}
+  <time datetime="{{page.meta.last_updated_iso}}" data-zp-local-date>
+    {{page.meta.last_updated}}
+  </time>
+{{/if}}
+```
+
+Client-side progressive enhancement may replace the fallback text with a localized date. The fallback remains useful when JavaScript is unavailable.
+
 `site.footer.copyright_text` is rendered by the bundled docs theme when present. If it is omitted, the bundled docs theme falls back to `site.title`. ZeroPress does not add a copyright symbol automatically.
 
 The bundled docs theme shows `Published with ZeroPress.` by default. Set `site.footer.attribution` to `false` to hide it.
@@ -509,12 +541,12 @@ cp ./_site/_zeropress/search_pagefind.js ./_site/_zeropress/search.js
 rm ./_site/_zeropress/search.json
 ```
 
-## Workspace Internal `.zeropress/` Files
+## Workspace Internal `.zeropress-build-page/` Files
 
-Build Pages reads optional site config from `<source>/.zeropress/config.json`. Separately, it writes internal working files to `.zeropress/` in the current working directory. These generated working files are not the final deploy output. The final static site is written to the `destination` directory.
+Build Pages reads optional user-authored site config from `<source>/.zeropress/config.json`. Separately, it writes generated internal working files to `.zeropress-build-page/` in the current working directory. These generated working files are not the final deploy output. The final static site is written to the `destination` directory.
 
 ```txt
-.zeropress/
+.zeropress-build-page/
   build-pages-config.json
   preview-data.json
   build-report.json

package/action.yml

@@ -17,7 +17,7 @@ inputs:
     required: false
     default: ./_site
   theme:
-    description: Bundled theme name. Currently supports "docs".
+    description: Bundled theme name. Supports "docs" and alias "docs1".
     required: false
     default: docs
   theme-path:

package/dist/action.js

@@ -53696,7 +53696,7 @@ async function validateThemeFiles(fileMap, options2 = {}) {
     }
     const content = getText(files.get(templatePath));
     templateContents.set(templatePath, content);
-    validateTemplateSyntax(templatePath, content, { errors, runtime: manifest?.runtime || DEFAULT_RUNTIME });
+    validateTemplateSyntax(templatePath, content, { errors, warnings, runtime: manifest?.runtime || DEFAULT_RUNTIME });
   }
   for (const [filePath, value] of files.entries()) {
     if (!filePath.startsWith("partials/") || !filePath.endsWith(".html")) {
@@ -53705,7 +53705,7 @@ async function validateThemeFiles(fileMap, options2 = {}) {
     const partialName = filePath.slice("partials/".length, -".html".length);
     const content = getText(value);
     partialContents.set(partialName, content);
-    validateTemplateSyntax(filePath, content, { errors, runtime: manifest?.runtime || DEFAULT_RUNTIME });
+    validateTemplateSyntax(filePath, content, { errors, warnings, runtime: manifest?.runtime || DEFAULT_RUNTIME });
   }
   validatePartialReferences(templateContents, partialContents, { errors, runtime: manifest?.runtime || DEFAULT_RUNTIME });
   return {
@@ -53922,10 +53922,22 @@ function validateManifest(themeJson) {
   return { errors, manifest: errors.length > 0 ? void 0 : manifest };
 }
 function validateTemplateSyntax(templatePath, content, context) {
-  const { errors } = context;
+  const { errors, warnings = [] } = context;
   const slotRegex = /\{\{slot:([a-zA-Z0-9_-]+)\}\}/g;
   const contentSlotMatches = content.match(/\{\{slot:content\}\}/g) || [];
   if (templatePath === "layout.html") {
+    if (!startsWithHtmlDoctype(content)) {
+      warnings.push(issue2(
+        "MISSING_DOCTYPE",
+        "layout.html",
+        "layout.html should start with <!doctype html> to keep browsers in standards mode",
+        "warning",
+        {
+          category: "theme_validation",
+          hint: "Add <!doctype html> before the opening <html> tag."
+        }
+      ));
+    }
     if (contentSlotMatches.length !== 1) {
       errors.push(issue2("INVALID_LAYOUT_SLOT", "layout.html", "layout.html must contain exactly one {{slot:content}}", "error"));
     }
@@ -53957,6 +53969,9 @@ function validateTemplateSyntax(templatePath, content, context) {
   }
   validateRuntimeV05TemplateSyntax(templatePath, content, errors);
 }
+function startsWithHtmlDoctype(content) {
+  return /^\s*(?:<!--[\s\S]*?-->\s*)*<!doctype\s+html\s*>/i.test(content);
+}
 function validateRuntimeV05TemplateSyntax(templatePath, content, errors) {
   const stack = [];
   let index = 0;
@@ -61874,8 +61889,12 @@ function attachCollectionCursors(posts, pages, collections) {
       if (!target) {
         return;
       }
+      const cursor = buildCollectionCursor(collectionId, collection, items, index);
       target.collection_cursors = target.collection_cursors || {};
-      target.collection_cursors[collectionId] = buildCollectionCursor(collectionId, collection, items, index);
+      target.collection_cursors[collectionId] = cursor;
+      if (!target.collection_cursor) {
+        target.collection_cursor = cursor;
+      }
     });
   }
 }
@@ -64222,9 +64241,13 @@ async function linkExists(siteDir, link2) {
 var __dirname = path3.dirname(fileURLToPath(import.meta.url));
 var packageDir = path3.resolve(__dirname, "..");
 var prebuildScript = __dirname === path3.join(packageDir, "dist") ? path3.join(__dirname, "prebuild.js") : path3.join(packageDir, "src", "prebuild.js");
-var PREVIEW_DATA_PATH = ".zeropress/preview-data.json";
-var STAGING_DIR = ".zeropress/public-assets";
-var DEFAULT_THEME = "docs";
+var INTERNAL_WORK_DIR = ".zeropress-build-page";
+var PREVIEW_DATA_PATH = `${INTERNAL_WORK_DIR}/preview-data.json`;
+var STAGING_DIR = `${INTERNAL_WORK_DIR}/public-assets`;
+var BUNDLED_THEME_ALIASES = /* @__PURE__ */ new Map([
+  ["docs", "docs"],
+  ["docs1", "docs"]
+]);
 async function runBuildPages(options2) {
   const cwd = path3.resolve(options2.cwd || process.cwd());
   const copyMarkdownSource = options2.copyMarkdownSource !== false;
@@ -64232,7 +64255,7 @@ async function runBuildPages(options2) {
   const publicDirExplicit = hasExplicitPublicDir(options2);
   const publicDir = publicDirExplicit ? path3.resolve(cwd, options2.publicDir) : sourceDir;
   const destinationDir = path3.resolve(cwd, options2.destination);
-  const generatedDir = path3.join(cwd, ".zeropress");
+  const generatedDir = path3.join(cwd, INTERNAL_WORK_DIR);
   const stagingDir = path3.join(cwd, STAGING_DIR);
   const previewDataPath = path3.join(cwd, PREVIEW_DATA_PATH);
   const themeDir = resolveThemeDir(cwd, options2);
@@ -64246,6 +64269,7 @@ async function runBuildPages(options2) {
     generatedDir
   });
   await assertDirectory(sourceDir, "Source directory");
+  await assertDirectory(themeDir, "Theme directory");
   await assertPublicDirectory(publicDir, publicDirExplicit);
   await assertDestinationPath(destinationDir);
   await fs3.rm(generatedDir, { recursive: true, force: true });
@@ -64289,7 +64313,7 @@ async function runBuildPages(options2) {
   process.env.ZEROPRESS_PUBLIC_DIR = stagingDir;
   try {
     const result = await runBuild(themeDir, previewData, destinationDir);
-    console.log("Built ZeroPress Pages site successfully");
+    console.log(formatBuildPagesSuccessMessage());
     console.log(`Files: ${result.files.length}`);
     console.log(`Output: ${formatPath(cwd, destinationDir)}`);
   } finally {
@@ -64310,14 +64334,36 @@ async function runBuildPages(options2) {
     console.log(`Checked ${result.htmlFiles.length} HTML files for internal links`);
   }
 }
+function formatBuildPagesSuccessMessage(stream = process.stdout) {
+  return createColor2(stream).green("Built ZeroPress Pages site successfully");
+}
+function createColor2(stream) {
+  const enabled = colorsEnabled(stream);
+  const wrap = (code2, value) => enabled ? `\x1B[${code2}m${value}\x1B[0m` : value;
+  return {
+    red: (value) => wrap("31", value),
+    yellow: (value) => wrap("33", value),
+    green: (value) => wrap("32", value)
+  };
+}
+function colorsEnabled(stream) {
+  if (process.env.NO_COLOR) {
+    return false;
+  }
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") {
+    return true;
+  }
+  return Boolean(stream?.isTTY);
+}
 function resolveThemeDir(cwd, options2) {
   if (options2.themePath) {
     return path3.resolve(cwd, options2.themePath);
   }
-  if (options2.theme === DEFAULT_THEME) {
-    return path3.join(packageDir, "themes", DEFAULT_THEME);
+  const canonicalTheme = BUNDLED_THEME_ALIASES.get(options2.theme);
+  if (canonicalTheme) {
+    return path3.join(packageDir, "themes", canonicalTheme);
   }
-  throw new Error(`Unknown bundled theme: ${options2.theme}`);
+  throw new Error(`Unknown bundled theme: ${options2.theme}. Supported bundled themes: ${Array.from(BUNDLED_THEME_ALIASES.keys()).join(", ")}`);
 }
 function hasExplicitPublicDir(options2) {
   return typeof options2.publicDir === "string" && Boolean(options2.publicDir.trim());
@@ -64389,11 +64435,11 @@ function assertBuildPagesPathLayout({
       `Public directory must be a dedicated asset directory, not the current working directory. Received: ${formatPath(cwd, publicDir)}`
     );
   }
-  assertNoPathOverlap(cwd, "Source directory", sourceDir, "internal .zeropress working directory", generatedDir);
-  assertNoPathOverlap(cwd, "Destination directory", destinationDir, "internal .zeropress working directory", generatedDir);
-  assertNoPathOverlap(cwd, "Theme directory", themeDir, "internal .zeropress working directory", generatedDir);
+  assertNoPathOverlap(cwd, "Source directory", sourceDir, `internal ${INTERNAL_WORK_DIR} working directory`, generatedDir);
+  assertNoPathOverlap(cwd, "Destination directory", destinationDir, `internal ${INTERNAL_WORK_DIR} working directory`, generatedDir);
+  assertNoPathOverlap(cwd, "Theme directory", themeDir, `internal ${INTERNAL_WORK_DIR} working directory`, generatedDir);
   if (!samePath(publicDir, sourceDir)) {
-    assertNoPathOverlap(cwd, "Public directory", publicDir, "internal .zeropress working directory", generatedDir);
+    assertNoPathOverlap(cwd, "Public directory", publicDir, `internal ${INTERNAL_WORK_DIR} working directory`, generatedDir);
     assertNoPathOverlap(cwd, "Public directory", publicDir, "destination directory", destinationDir);
     assertNoPathOverlap(cwd, "Public directory", publicDir, "theme directory", themeDir);
   }

package/dist/prebuild.js

@@ -3519,15 +3519,18 @@ var require_gray_matter = __commonJS({
 // src/prebuild.js
 var import_gray_matter = __toESM(require_gray_matter(), 1);
 import fs from "node:fs/promises";
+import { execFile } from "node:child_process";
 import path from "node:path";
+import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var execFileAsync = promisify(execFile);
 var rootDir = process.cwd();
 var sourceDir = resolveEnvPath(["ZEROPRESS_BUILD_PAGES_SOURCE"], "docs");
 var publicDir = resolveEnvPath(["ZEROPRESS_BUILD_PAGES_PUBLIC_DIR"], sourceDir);
 var defaultConfigPath = path.join(sourceDir, ".zeropress", "config.json");
 var configPath = resolveOptionalEnvPath(["ZEROPRESS_BUILD_PAGES_CONFIG"], defaultConfigPath);
-var outDir = path.join(rootDir, ".zeropress");
+var outDir = path.join(rootDir, ".zeropress-build-page");
 var buildPagesConfigPath = path.join(outDir, "build-pages-config.json");
 var previewDataPath = path.join(outDir, "preview-data.json");
 var buildReportPath = path.join(outDir, "build-report.json");
@@ -3541,6 +3544,7 @@ var FRONT_MATTER_DATA_MAX_DEPTH = 4;
 var FRONT_MATTER_DATA_MAX_KEYS = 64;
 var FRONT_MATTER_DATA_MAX_ARRAY_LENGTH = 256;
 var FRONT_MATTER_DISCOVERABILITY_VALUES = /* @__PURE__ */ new Set(["default", "noindex", "delist"]);
+var MARKDOWN_LAST_UPDATED_VALUES = /* @__PURE__ */ new Set(["none", "git"]);
 var markdownDiscoverExcludeRoots = buildMarkdownDiscoverExcludeRoots();
 var PrebuildMarkdownError = class extends Error {
   constructor(sourcePath, reason, expected = "", code = "invalid_markdown") {
@@ -3569,10 +3573,12 @@ async function main() {
   );
   const menus = normalizeMenus(config.menus);
   const customHtmlConfig = normalizeCustomHtmlConfig(config.custom_html);
+  const markdownConfig = normalizeMarkdownConfig(config.markdown);
   const resolvedConfig = buildResolvedConfig(config, {
     frontPageConfig,
     menus,
-    customHtmlConfig
+    customHtmlConfig,
+    markdownConfig
   });
   const sourceFiles = await listMarkdownFiles(sourceDir);
   const skippedMarkdown = [];
@@ -3607,21 +3613,29 @@ async function main() {
   const routeBySourcePath = new Map(
     pageInputs.map(({ sourcePath, route }) => [sourcePath, route])
   );
-  const pages = pageInputs.map(({ sourcePath, bodyMarkdown, frontMatter, title, route }) => ({
-    title,
-    slug: route.slug,
-    path: route.path,
-    meta: {
-      ...frontMatter.meta,
-      ...copyMarkdownSource ? { source_markdown_url: buildSourceMarkdownUrl(sourcePath) } : {}
-    },
-    ...frontMatter.data !== void 0 ? { data: frontMatter.data } : {},
-    ...frontMatter.discoverability !== "default" ? { discoverability: frontMatter.discoverability } : {},
-    content: rewriteMarkdownLinks(bodyMarkdown, sourcePath, routeBySourcePath),
-    document_type: "markdown",
-    excerpt: frontMatter.description || extractExcerpt(bodyMarkdown, title),
-    status: "published"
-  }));
+  const collections = normalizeCollections(config.collections, pageInputs, skippedMarkdown);
+  if (Object.keys(collections).length > 0) {
+    resolvedConfig.collections = collections;
+  }
+  const pages = [];
+  for (const { sourcePath, bodyMarkdown, frontMatter, title, route } of pageInputs) {
+    const meta = await buildPageMeta(sourcePath, frontMatter, markdownConfig);
+    pages.push({
+      title,
+      slug: route.slug,
+      path: route.path,
+      meta: {
+        ...meta,
+        ...copyMarkdownSource ? { source_markdown_url: buildSourceMarkdownUrl(sourcePath) } : {}
+      },
+      ...frontMatter.data !== void 0 ? { data: frontMatter.data } : {},
+      ...frontMatter.discoverability !== "default" ? { discoverability: frontMatter.discoverability } : {},
+      content: rewriteMarkdownLinks(bodyMarkdown, sourcePath, routeBySourcePath),
+      document_type: "markdown",
+      excerpt: frontMatter.description || extractExcerpt(bodyMarkdown, title),
+      status: "published"
+    });
+  }
   const frontPageResult = await buildFrontPageData(frontPageConfig, pageInputs, resolvedConfig);
   if (frontPageResult.page) {
     pages.push(frontPageResult.page);
@@ -3644,6 +3658,9 @@ async function main() {
     menus,
     widgets: {}
   };
+  if (Object.keys(collections).length > 0) {
+    previewData.collections = collections;
+  }
   if (customHtml) {
     previewData.custom_html = customHtml;
   }
@@ -3756,11 +3773,12 @@ function buildSiteData(config, frontPage) {
   }
   return site;
 }
-function buildResolvedConfig(config, { frontPageConfig, menus, customHtmlConfig }) {
+function buildResolvedConfig(config, { frontPageConfig, menus, customHtmlConfig, markdownConfig }) {
   const resolvedConfig = {
     $schema: BUILD_PAGES_CONFIG_SCHEMA_URL,
     version: "0.1",
     site: normalizeSiteConfig(config.site),
+    markdown: markdownConfig,
     front_page: frontPageConfig,
     menus
   };
@@ -3769,6 +3787,23 @@ function buildResolvedConfig(config, { frontPageConfig, menus, customHtmlConfig
   }
   return resolvedConfig;
 }
+function normalizeMarkdownConfig(value) {
+  if (value === void 0) {
+    return {
+      last_updated: "none"
+    };
+  }
+  if (!isPlainObject(value)) {
+    throw new PrebuildConfigError(
+      "markdown must be an object.",
+      '  "markdown": { "last_updated": "git" }'
+    );
+  }
+  assertKnownConfigKeys(value, ["last_updated"], "markdown");
+  return {
+    last_updated: normalizeLastUpdatedPolicy(value.last_updated, "markdown.last_updated", PrebuildConfigError)
+  };
+}
 function normalizeSiteConfig(value) {
   if (value !== void 0 && !isPlainObject(value)) {
     throw new PrebuildConfigError(
@@ -4260,6 +4295,69 @@ function defaultMenus() {
     }
   };
 }
+function normalizeCollections(value, pageInputs, skippedMarkdown) {
+  if (value === void 0) {
+    return {};
+  }
+  if (!isPlainObject(value)) {
+    throw new PrebuildConfigError("collections must be an object keyed by collection id.");
+  }
+  const pageBySourcePath = new Map(pageInputs.map((pageInput) => [pageInput.sourcePath, pageInput]));
+  const skippedByFile = new Map(
+    skippedMarkdown.map((entry) => [path.resolve(rootDir, entry.file), entry.reason])
+  );
+  const collections = {};
+  for (const [collectionId, collection] of Object.entries(value)) {
+    validateConfigId(collectionId, `collections.${collectionId}`);
+    if (!isPlainObject(collection)) {
+      throw new PrebuildConfigError(`collections.${collectionId} must be an object.`);
+    }
+    assertKnownConfigKeys(collection, ["title", "description", "items"], `collections.${collectionId}`);
+    if (!Array.isArray(collection.items)) {
+      throw new PrebuildConfigError(`collections.${collectionId}.items must be an array of Markdown source paths.`);
+    }
+    const seenSourcePaths = /* @__PURE__ */ new Set();
+    const items = collection.items.map((item, index) => {
+      const pathLabel = `collections.${collectionId}.items[${index}]`;
+      const normalizedPath = resolveCollectionSourcePath(item, pathLabel);
+      const sourcePath = path.resolve(sourceDir, normalizedPath);
+      if (seenSourcePaths.has(sourcePath)) {
+        throw new PrebuildConfigError(`${pathLabel} duplicates ${normalizedPath} in collections.${collectionId}.`);
+      }
+      seenSourcePaths.add(sourcePath);
+      const pageInput = pageBySourcePath.get(sourcePath);
+      if (!pageInput) {
+        const skippedReason = skippedByFile.get(sourcePath);
+        if (skippedReason) {
+          throw new PrebuildConfigError(`${pathLabel} references skipped Markdown ${normalizedPath}: ${skippedReason}`);
+        }
+        throw new PrebuildConfigError(`${pathLabel} was not discovered as a Markdown page: ${normalizedPath}`);
+      }
+      return {
+        type: "page",
+        slug: pageInput.route.slug
+      };
+    });
+    collections[collectionId] = {
+      title: readConfigString(collection.title, collectionId),
+      ...collection.description !== void 0 ? { description: readConfigString(collection.description, "") } : {},
+      items
+    };
+  }
+  return collections;
+}
+function resolveCollectionSourcePath(value, pathLabel) {
+  const normalizedPath = normalizeSourceFilePath(value, pathLabel);
+  if (!normalizedPath.toLowerCase().endsWith(".md")) {
+    throw new PrebuildConfigError(`${pathLabel} must be a Markdown source path ending in .md.`);
+  }
+  return normalizedPath;
+}
+function validateConfigId(value, pathLabel) {
+  if (!/^[a-z][a-z0-9_-]{0,63}$/.test(value)) {
+    throw new PrebuildConfigError(`${pathLabel} must use a lowercase config id such as "docs" or "reference-guides".`);
+  }
+}
 function buildPrebuildReport({
   sourceFiles,
   pageInputs,
@@ -4368,11 +4466,37 @@ function normalizePublishedFrontMatter(frontMatter, sourcePath) {
     title: normalizeFrontMatterTitle(frontMatter.title, sourcePath),
     description: normalizeFrontMatterDescription(frontMatter.description, sourcePath),
     path: normalizeFrontMatterRoutePath(frontMatter.path, sourcePath),
+    last_updated: normalizeFrontMatterLastUpdated(frontMatter.last_updated, sourcePath),
     discoverability: normalizeFrontMatterDiscoverability(frontMatter.discoverability, sourcePath),
     meta: normalizeFrontMatterMeta(frontMatter.meta, sourcePath),
     data: normalizeFrontMatterData(frontMatter.data, sourcePath)
   };
 }
+function normalizeLastUpdatedPolicy(value, pathLabel, ErrorClass, sourcePath = null) {
+  if (value === void 0) {
+    return "none";
+  }
+  if (typeof value === "string" && MARKDOWN_LAST_UPDATED_VALUES.has(value)) {
+    return value;
+  }
+  if (ErrorClass === PrebuildMarkdownError) {
+    throw new ErrorClass(
+      sourcePath,
+      `${pathLabel} must be one of: ${Array.from(MARKDOWN_LAST_UPDATED_VALUES).join(", ")}.`,
+      "  last_updated: none\n  last_updated: git"
+    );
+  }
+  throw new ErrorClass(
+    `${pathLabel} must be one of: ${Array.from(MARKDOWN_LAST_UPDATED_VALUES).join(", ")}.`,
+    '  "markdown": { "last_updated": "none" }\n  "markdown": { "last_updated": "git" }'
+  );
+}
+function normalizeFrontMatterLastUpdated(value, sourcePath) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return normalizeLastUpdatedPolicy(value, "front matter last_updated", PrebuildMarkdownError, sourcePath);
+}
 function normalizeFrontMatterTitle(value, sourcePath) {
   if (value === void 0) {
     return "";
@@ -4456,6 +4580,74 @@ function normalizeFrontMatterMeta(value, sourcePath) {
   }
   return meta;
 }
+async function buildPageMeta(sourcePath, frontMatter, markdownConfig) {
+  const meta = {
+    ...frontMatter.meta
+  };
+  if (hasManualLastUpdatedMeta(meta)) {
+    return meta;
+  }
+  const lastUpdatedPolicy = frontMatter.last_updated || markdownConfig.last_updated;
+  if (lastUpdatedPolicy !== "git") {
+    return meta;
+  }
+  const lastUpdatedIso = await readGitLastUpdatedIso(sourcePath);
+  if (!lastUpdatedIso) {
+    return meta;
+  }
+  return {
+    ...meta,
+    last_updated_iso: lastUpdatedIso,
+    last_updated: lastUpdatedIso.slice(0, 10)
+  };
+}
+function hasManualLastUpdatedMeta(meta) {
+  return Object.hasOwn(meta, "last_updated") || Object.hasOwn(meta, "last_updated_iso");
+}
+async function readGitLastUpdatedIso(sourcePath) {
+  const realSourcePath = await resolveRealPath(sourcePath);
+  const realRootDir = await resolveRealPath(rootDir);
+  const gitPath = path.relative(realRootDir, realSourcePath);
+  try {
+    const { stdout } = await execFileAsync("git", [
+      "-C",
+      realRootDir,
+      "log",
+      "-1",
+      "--format=%cI",
+      "--",
+      gitPath
+    ], {
+      encoding: "utf8"
+    });
+    const value = stdout.trim();
+    if (!value) {
+      warnGitLastUpdated(sourcePath, "no commit date was found for this file.");
+      return "";
+    }
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(value)) {
+      warnGitLastUpdated(sourcePath, `unexpected git date output: ${value}`);
+      return "";
+    }
+    return value;
+  } catch (error) {
+    warnGitLastUpdated(sourcePath, error instanceof Error ? error.message : String(error));
+    return "";
+  }
+}
+async function resolveRealPath(value) {
+  try {
+    return await fs.realpath(value);
+  } catch {
+    return value;
+  }
+}
+function warnGitLastUpdated(sourcePath, reason) {
+  console.warn([
+    `[zeropress-build-pages] Warning: could not read git last_updated for ${formatSourcePath(sourcePath)}.`,
+    `Reason: ${reason}`
+  ].join("\n"));
+}
 function isPreviewMetaValue(value) {
   return value === null || typeof value === "string" || typeof value === "number" && Number.isFinite(value) || typeof value === "boolean";
 }
@@ -4673,9 +4865,11 @@ function buildRoutePath(relativeSourcePath, sourcePath, options2 = {}) {
   return routePath;
 }
 function buildSlug(routePath) {
-  const segments = routePath.split("/");
-  const rawSlug = segments.at(-1) === "index" && segments.length > 1 ? segments.at(-2) : segments.at(-1);
-  return sanitizePathSegment(rawSlug || "");
+  const segments = routePath.split("/").filter(Boolean);
+  if (segments.length > 1 && segments.at(-1) === "index") {
+    segments.pop();
+  }
+  return sanitizePathSegment(segments.join("-") || "index");
 }
 function sanitizePathSegment(segment) {
   return segment.replace(/[^a-z0-9.-]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeropress/build-pages",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "ZeroPress Markdown build action and CLI for static hosting",
   "type": "module",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "node": ">=18.18.0"
   },
   "dependencies": {
-    "@zeropress/build": "0.6.3",
+    "@zeropress/build": "0.6.4",
     "gray-matter": "4.0.3"
   },
   "devDependencies": {