@zeropress/build-pages 0.6.2 → 0.6.4

package/src/index.js

@@ -10,12 +10,21 @@ const packageDir = path.resolve(__dirname, '..');
 const prebuildScript = __dirname === path.join(packageDir, 'dist')
   ? path.join(__dirname, 'prebuild.js')
   : path.join(packageDir, 'src', 'prebuild.js');
-const PREVIEW_DATA_PATH = '.zeropress/preview-data.json';
-const STAGING_DIR = '.zeropress/public-assets';
+const INTERNAL_WORK_DIR = '.zeropress-build-page';
+const PREVIEW_DATA_PATH = `${INTERNAL_WORK_DIR}/preview-data.json`;
+const STAGING_DIR = `${INTERNAL_WORK_DIR}/public-assets`;
 const DEFAULT_THEME = 'docs';
+const BUNDLED_THEME_ALIASES = new Map([
+  ['docs', 'docs'],
+  ['docs1', 'docs'],
+]);
 
 export async function runCli(argv = process.argv.slice(2)) {
   try {
+    if (argv.length === 0) {
+      printHelp();
+      return;
+    }
     if (argv.includes('--help') || argv.includes('-h')) {
       printHelp();
       return;
@@ -30,7 +39,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     await runBuildPages(options);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    console.error(message);
+    console.error(colorizeError(prefixError(message)));
     process.exitCode = 1;
   }
 }
@@ -42,7 +51,7 @@ export async function runBuildPages(options) {
   const publicDirExplicit = hasExplicitPublicDir(options);
   const publicDir = publicDirExplicit ? path.resolve(cwd, options.publicDir) : sourceDir;
   const destinationDir = path.resolve(cwd, options.destination);
-  const generatedDir = path.join(cwd, '.zeropress');
+  const generatedDir = path.join(cwd, INTERNAL_WORK_DIR);
   const stagingDir = path.join(cwd, STAGING_DIR);
   const previewDataPath = path.join(cwd, PREVIEW_DATA_PATH);
   const themeDir = resolveThemeDir(cwd, options);
@@ -57,6 +66,7 @@ export async function runBuildPages(options) {
     generatedDir,
   });
   await assertDirectory(sourceDir, 'Source directory');
+  await assertDirectory(themeDir, 'Theme directory');
   await assertPublicDirectory(publicDir, publicDirExplicit);
   await assertDestinationPath(destinationDir);
   await fs.rm(generatedDir, { recursive: true, force: true });
@@ -104,7 +114,7 @@ export async function runBuildPages(options) {
   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 {
@@ -164,6 +174,10 @@ export function parseArgs(argv) {
       continue;
     }
 
+    if (!arg.startsWith('--')) {
+      throw new Error(`Invalid arguments: unexpected positional argument: ${arg}. Use --source <dir> and --destination <dir>.`);
+    }
+
     throw new Error(`Invalid arguments: unknown option ${arg}`);
   }
 
@@ -200,7 +214,7 @@ Options:
   --source <dir>                Dedicated source directory (required)
   --public-dir <dir>            Public passthrough directory (default: source)
   --destination <dir>           Output directory (required)
-  --theme docs                  Bundled theme name (default: docs)
+  --theme docs                  Bundled theme name (default: docs; docs1 aliases docs)
   --theme-path <dir>            Custom ZeroPress theme directory
   --config <path>               Config file (default: <source>/.zeropress/config.json)
   --site-url <url>              Canonical site URL override
@@ -211,14 +225,58 @@ Options:
   --version, -v                 Show version`);
 }
 
+function prefixError(message) {
+  if (message.startsWith('[zeropress-build-pages]')) {
+    return message;
+  }
+  return `[zeropress-build-pages] ${message}`;
+}
+
+export function formatBuildPagesSuccessMessage(stream = process.stdout) {
+  return createColor(stream).green('Built ZeroPress Pages site successfully');
+}
+
+function colorizeError(message) {
+  if (!colorsEnabled(process.stderr)) {
+    return message;
+  }
+
+  return message
+    .replace(/^(\[zeropress-build-pages\].*)/m, '\x1b[31m$1\x1b[0m')
+    .replace(/\bERROR\b/g, '\x1b[31mERROR\x1b[0m')
+    .replace(/\bWARN\b/g, '\x1b[33mWARN\x1b[0m')
+    .replace(/\bHint:/g, '\x1b[1mHint:\x1b[0m');
+}
+
+function createColor(stream) {
+  const enabled = colorsEnabled(stream);
+  const wrap = (code, value) => (enabled ? `\x1b[${code}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, options) {
   if (options.themePath) {
     return path.resolve(cwd, options.themePath);
   }
-  if (options.theme === DEFAULT_THEME) {
-    return path.join(packageDir, 'themes', DEFAULT_THEME);
+  const canonicalTheme = BUNDLED_THEME_ALIASES.get(options.theme);
+  if (canonicalTheme) {
+    return path.join(packageDir, 'themes', canonicalTheme);
   }
-  throw new Error(`Unknown bundled theme: ${options.theme}`);
+  throw new Error(`Unknown bundled theme: ${options.theme}. Supported bundled themes: ${Array.from(BUNDLED_THEME_ALIASES.keys()).join(', ')}`);
 }
 
 function hasExplicitPublicDir(options) {
@@ -303,11 +361,11 @@ function assertBuildPagesPathLayout({
     );
   }
 
-  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/src/prebuild.js

@@ -1,28 +1,32 @@
 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';
 import matter from 'gray-matter';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const execFileAsync = promisify(execFile);
 const rootDir = process.cwd();
 const sourceDir = resolveEnvPath(['ZEROPRESS_BUILD_PAGES_SOURCE'], 'docs');
 const publicDir = resolveEnvPath(['ZEROPRESS_BUILD_PAGES_PUBLIC_DIR'], sourceDir);
 const defaultConfigPath = path.join(sourceDir, '.zeropress', 'config.json');
 const configPath = resolveOptionalEnvPath(['ZEROPRESS_BUILD_PAGES_CONFIG'], defaultConfigPath);
-const outDir = path.join(rootDir, '.zeropress');
+const outDir = path.join(rootDir, '.zeropress-build-page');
 const buildPagesConfigPath = path.join(outDir, 'build-pages-config.json');
 const previewDataPath = path.join(outDir, 'preview-data.json');
 const buildReportPath = path.join(outDir, 'build-report.json');
 const skipUntitledMarkdown = readBooleanEnv('ZEROPRESS_SKIP_UNTITLED_MARKDOWN');
 const copyMarkdownSource = readBooleanEnv('ZEROPRESS_COPY_MARKDOWN_SOURCE', true);
 const FRONT_PAGE_TYPES = new Set(['theme_index', 'markdown', 'html']);
-const BUILD_PAGES_CONFIG_SCHEMA_URL = 'https://zeropress.dev/schemas/zeropress-build-pages.config.v0.1.schema.json';
-const PREVIEW_DATA_SCHEMA_URL = 'https://zeropress.dev/schemas/preview-data.v0.6.schema.json';
+const BUILD_PAGES_CONFIG_SCHEMA_URL = 'https://schemas.zeropress.dev/build-pages-config/v0.1/schema.json';
+const PREVIEW_DATA_SCHEMA_URL = 'https://schemas.zeropress.dev/preview-data/v0.6/schema.json';
 const FRONT_MATTER_DATA_KEY_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*(?:-[a-zA-Z0-9_]+)*$/;
 const FRONT_MATTER_DATA_MAX_DEPTH = 4;
 const FRONT_MATTER_DATA_MAX_KEYS = 64;
 const FRONT_MATTER_DATA_MAX_ARRAY_LENGTH = 256;
 const FRONT_MATTER_DISCOVERABILITY_VALUES = new Set(['default', 'noindex', 'delist']);
+const MARKDOWN_LAST_UPDATED_VALUES = new Set(['none', 'git']);
 const markdownDiscoverExcludeRoots = buildMarkdownDiscoverExcludeRoots();
 
 class PrebuildMarkdownError extends Error {
@@ -55,10 +59,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,
+    markdownConfig,
   });
   const sourceFiles = await listMarkdownFiles(sourceDir);
   const skippedMarkdown = [];
@@ -97,22 +103,30 @@ async function main() {
   const routeBySourcePath = new Map(
     pageInputs.map(({ sourcePath, route }) => [sourcePath, route]),
   );
+  const collections = normalizeCollections(config.collections, pageInputs, skippedMarkdown);
+  if (Object.keys(collections).length > 0) {
+    resolvedConfig.collections = collections;
+  }
 
-  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 !== undefined ? { 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 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 !== undefined ? { 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) {
@@ -138,6 +152,10 @@ async function main() {
     menus,
     widgets: {},
   };
+
+  if (Object.keys(collections).length > 0) {
+    previewData.collections = collections;
+  }
   if (customHtml) {
     previewData.custom_html = customHtml;
   }
@@ -232,7 +250,7 @@ function buildSiteData(config, frontPage) {
     description: configuredSite.description,
     url: configuredSite.url,
     media_base_url: '',
-    locale: 'en-US',
+    locale: configuredSite.locale,
     posts_per_page: 10,
     datetime_display: 'static',
     date_style: 'medium',
@@ -249,6 +267,14 @@ function buildSiteData(config, frontPage) {
     indexing: configuredSite.indexing !== false,
   };
 
+  if (configuredSite.logo) {
+    site.logo = configuredSite.logo;
+  }
+
+  if (configuredSite.meta !== undefined) {
+    site.meta = configuredSite.meta;
+  }
+
   if (configuredSite.footer) {
     site.footer = configuredSite.footer;
   }
@@ -256,11 +282,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,
   };
@@ -272,6 +299,25 @@ function buildResolvedConfig(config, { frontPageConfig, menus, customHtmlConfig
   return resolvedConfig;
 }
 
+function normalizeMarkdownConfig(value) {
+  if (value === undefined) {
+    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 !== undefined && !isPlainObject(value)) {
     throw new PrebuildConfigError(
@@ -281,24 +327,98 @@ function normalizeSiteConfig(value) {
   }
 
   const configuredSite = isPlainObject(value) ? value : {};
-  assertKnownConfigKeys(configuredSite, ['title', 'description', 'url', 'expose_generator', 'search', 'indexing', 'footer'], 'site');
+  assertKnownConfigKeys(configuredSite, ['title', 'description', 'url', 'logo', 'locale', 'expose_generator', 'search', 'indexing', 'footer', 'meta'], 'site');
   const site = {
     title: readConfigString(configuredSite.title, 'Documentation'),
     description: readConfigString(configuredSite.description, 'A documentation site.'),
     url: readEnv('ZEROPRESS_SITE_URL', readConfigString(configuredSite.url, '')),
+    locale: normalizeSiteLocale(configuredSite.locale),
     expose_generator: readConfigBoolean(configuredSite.expose_generator, true, 'site.expose_generator'),
     search: readConfigBoolean(configuredSite.search, true, 'site.search'),
     indexing: readConfigBoolean(configuredSite.indexing, true, 'site.indexing'),
   };
 
+  const logo = normalizeSiteLogo(configuredSite.logo);
+  if (logo) {
+    site.logo = logo;
+  }
+
   const footer = normalizeFooter(configuredSite.footer);
   if (footer) {
     site.footer = footer;
   }
 
+  if (configuredSite.meta !== undefined) {
+    site.meta = normalizeSiteMeta(configuredSite.meta, 'site.meta');
+  }
+
   return site;
 }
 
+function normalizeSiteLocale(value) {
+  if (value === undefined) {
+    return 'en-US';
+  }
+  if (typeof value !== 'string') {
+    throw new PrebuildConfigError('site.locale must be a string when provided.');
+  }
+
+  const locale = value.trim();
+  if (locale.length < 2) {
+    throw new PrebuildConfigError('site.locale must be a non-empty locale string such as "en-US" or "ko-KR".');
+  }
+
+  return locale;
+}
+
+function normalizeSiteLogo(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!isPlainObject(value)) {
+    throw new PrebuildConfigError('site.logo must be an object when provided.');
+  }
+  assertKnownConfigKeys(value, ['src', 'alt'], 'site.logo');
+
+  const src = readConfigString(value.src, '');
+  if (!src) {
+    throw new PrebuildConfigError(
+      'site.logo.src must be a non-empty URL-like string.',
+      '  "logo": { "src": "/logo.svg", "alt": "My Site" }',
+    );
+  }
+  validateUrlLikeString(src, 'site.logo.src');
+
+  const logo = { src };
+  if (value.alt !== undefined) {
+    if (typeof value.alt !== 'string') {
+      throw new PrebuildConfigError('site.logo.alt must be a string when provided.');
+    }
+    const alt = value.alt.trim();
+    if (alt) {
+      logo.alt = alt;
+    }
+  }
+
+  return logo;
+}
+
+function normalizeSiteMeta(value, pathLabel) {
+  if (!isPlainObject(value)) {
+    throw new PrebuildConfigError(`${pathLabel} must be an object when provided.`);
+  }
+
+  const meta = {};
+  for (const [key, metaValue] of Object.entries(value)) {
+    if (!isPreviewMetaValue(metaValue)) {
+      throw new PrebuildConfigError(`${pathLabel}.${key} must be a string, number, boolean, or null.`);
+    }
+    meta[key] = metaValue;
+  }
+
+  return meta;
+}
+
 function normalizeFooter(value) {
   if (value === undefined) {
     return undefined;
@@ -324,6 +444,25 @@ function normalizeFooter(value) {
   return Object.keys(footer).length ? footer : undefined;
 }
 
+function validateUrlLikeString(value, pathLabel) {
+  if (value.startsWith('//')) {
+    throw new PrebuildConfigError(`${pathLabel} must be an absolute URL or a safe relative path.`);
+  }
+
+  if (value.startsWith('/') || value.startsWith('./') || value.startsWith('../')) {
+    return;
+  }
+
+  try {
+    const url = new URL(value);
+    if (!url.protocol || !url.hostname) {
+      throw new Error('missing host');
+    }
+  } catch {
+    throw new PrebuildConfigError(`${pathLabel} must be an absolute URL or a safe relative path.`);
+  }
+}
+
 function readConfigBoolean(value, fallback, pathName) {
   if (value === undefined) {
     return fallback;
@@ -752,6 +891,79 @@ function defaultMenus() {
   };
 }
 
+function normalizeCollections(value, pageInputs, skippedMarkdown) {
+  if (value === undefined) {
+    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 = 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 !== undefined ? { 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,
@@ -869,12 +1081,42 @@ 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 === undefined) {
+    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 === undefined) {
+    return undefined;
+  }
+  return normalizeLastUpdatedPolicy(value, 'front matter last_updated', PrebuildMarkdownError, sourcePath);
+}
+
 function normalizeFrontMatterTitle(value, sourcePath) {
   if (value === undefined) {
     return '';
@@ -981,6 +1223,87 @@ 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
@@ -1257,11 +1580,11 @@ function buildRoutePath(relativeSourcePath, sourcePath, options = {}) {
 }
 
 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) {

package/themes/docs/404.html

@@ -1,6 +1,17 @@
 <section class="shell not-found">
-  <p class="eyebrow">404</p>
+  <p class="eyebrow eyebrow--error">
+    <span class="eyebrow__dot" aria-hidden="true"></span>
+    404
+  </p>
   <h1>Page not found</h1>
   <p class="lede">The page you are looking for is not part of the current documentation build.</p>
-  <a class="button-link" href="/">Return home</a>
+  <div class="hero__actions">
+    <a class="button-link" href="/">
+      Return home
+      <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+        <line x1="5" y1="12" x2="19" y2="12"></line>
+        <polyline points="12 5 19 12 12 19"></polyline>
+      </svg>
+    </a>
+  </div>
 </section>