@zeropress/build-pages 0.6.3 → 0.6.4

package/schemas/zeropress-build-pages.config.v0.1.schema.json

@@ -21,6 +21,9 @@
     "site": {
       "$ref": "#/$defs/site"
     },
+    "markdown": {
+      "$ref": "#/$defs/markdown"
+    },
     "front_page": {
       "$ref": "#/$defs/frontPage"
     },
@@ -29,6 +32,9 @@
     },
     "menus": {
       "$ref": "#/$defs/menus"
+    },
+    "collections": {
+      "$ref": "#/$defs/collections"
     }
   },
   "$defs": {
@@ -124,6 +130,21 @@
         }
       }
     },
+    "markdown": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Markdown source processing options.",
+      "markdownDescription": "Markdown source processing options.",
+      "properties": {
+        "last_updated": {
+          "type": "string",
+          "enum": ["none", "git"],
+          "default": "none",
+          "description": "Optional page meta enrichment. none does not generate last_updated values; git reads the latest commit date for each Markdown file.",
+          "markdownDescription": "Optional page meta enrichment. `none` does not generate `last_updated` values; `git` reads the latest commit date for each Markdown file."
+        }
+      }
+    },
     "frontPage": {
       "type": "object",
       "additionalProperties": false,
@@ -319,6 +340,40 @@
           "default": []
         }
       }
+    },
+    "collections": {
+      "type": "object",
+      "description": "Reading-order collections generated from Markdown source paths.",
+      "markdownDescription": "Reading-order collections generated from Markdown source paths.",
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/collection"
+      }
+    },
+    "collection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["items"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string"
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^\\\\?#]+\\.md$"
+          }
+        }
+      }
     }
   },
   "examples": [
@@ -344,6 +399,9 @@
       "front_page": {
         "type": "markdown"
       },
+      "markdown": {
+        "last_updated": "git"
+      },
       "custom_html": {
         "head_end": {
           "file": ".zeropress/head-end.html"
@@ -367,6 +425,15 @@
             }
           ]
         }
+      },
+      "collections": {
+        "guides": {
+          "title": "Guides",
+          "items": [
+            "getting-started/index.md",
+            "deployment/index.md"
+          ]
+        }
       }
     }
   ]

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,15 +1,18 @@
 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');
@@ -23,6 +26,7 @@ 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;
   }
@@ -264,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,
   };
@@ -280,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(
@@ -853,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,
@@ -970,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 '';
@@ -1082,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
@@ -1358,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/assets/style.css

@@ -200,14 +200,9 @@ a:hover {
   top: 0;
   z-index: 20;
   background: var(--header-bg);
-  border-bottom: 1px solid transparent;
+  border-bottom: 1px solid var(--line);
   backdrop-filter: saturate(140%) blur(14px);
   -webkit-backdrop-filter: saturate(140%) blur(14px);
-  transition: border-color 200ms var(--ease), background 200ms var(--ease);
-}
-
-.site-header.is-scrolled {
-  border-bottom-color: var(--line);
 }
 
 .site-header__inner {
@@ -451,7 +446,11 @@ a:hover {
   transition: border-color 120ms var(--ease), background 120ms var(--ease), color 120ms var(--ease);
 }
 
-.theme-toggle:hover {
+.theme-toggle:disabled {
+  cursor: not-allowed;
+}
+
+.theme-toggle:not(:disabled):hover {
   border-color: var(--line-strong);
   color: var(--accent);
 }