@zeropress/build-pages 0.6.1 → 0.6.3

package/dist/prebuild.js

@@ -3524,6 +3524,7 @@ import { fileURLToPath } from "node:url";
 var __dirname = path.dirname(fileURLToPath(import.meta.url));
 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");
@@ -3533,13 +3534,14 @@ var buildReportPath = path.join(outDir, "build-report.json");
 var skipUntitledMarkdown = readBooleanEnv("ZEROPRESS_SKIP_UNTITLED_MARKDOWN");
 var copyMarkdownSource = readBooleanEnv("ZEROPRESS_COPY_MARKDOWN_SOURCE", true);
 var FRONT_PAGE_TYPES = /* @__PURE__ */ new Set(["theme_index", "markdown", "html"]);
-var BUILD_PAGES_CONFIG_SCHEMA_URL = "https://zeropress.dev/schemas/zeropress-build-pages.config.v0.1.schema.json";
-var PREVIEW_DATA_SCHEMA_URL = "https://zeropress.dev/schemas/preview-data.v0.6.schema.json";
+var BUILD_PAGES_CONFIG_SCHEMA_URL = "https://schemas.zeropress.dev/build-pages-config/v0.1/schema.json";
+var PREVIEW_DATA_SCHEMA_URL = "https://schemas.zeropress.dev/preview-data/v0.6/schema.json";
 var FRONT_MATTER_DATA_KEY_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*(?:-[a-zA-Z0-9_]+)*$/;
 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 markdownDiscoverExcludeRoots = buildMarkdownDiscoverExcludeRoots();
 var PrebuildMarkdownError = class extends Error {
   constructor(sourcePath, reason, expected = "", code = "invalid_markdown") {
     super(reason);
@@ -3727,7 +3729,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",
@@ -3740,8 +3742,15 @@ function buildSiteData(config, frontPage) {
     },
     disallow_comments: true,
     expose_generator: configuredSite.expose_generator !== false,
+    search: configuredSite.search !== false,
     indexing: configuredSite.indexing !== false
   };
+  if (configuredSite.logo) {
+    site.logo = configuredSite.logo;
+  }
+  if (configuredSite.meta !== void 0) {
+    site.meta = configuredSite.meta;
+  }
   if (configuredSite.footer) {
     site.footer = configuredSite.footer;
   }
@@ -3768,20 +3777,83 @@ function normalizeSiteConfig(value) {
     );
   }
   const configuredSite = isPlainObject(value) ? value : {};
-  assertKnownConfigKeys(configuredSite, ["title", "description", "url", "expose_generator", "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 !== void 0) {
+    site.meta = normalizeSiteMeta(configuredSite.meta, "site.meta");
+  }
   return site;
 }
+function normalizeSiteLocale(value) {
+  if (value === void 0) {
+    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 === void 0) {
+    return void 0;
+  }
+  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 !== void 0) {
+    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 === void 0) {
     return void 0;
@@ -3803,6 +3875,22 @@ function normalizeFooter(value) {
   }
   return Object.keys(footer).length ? footer : void 0;
 }
+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 === void 0) {
     return fallback;
@@ -4184,6 +4272,7 @@ function buildPrebuildReport({
   return {
     generated_at: (/* @__PURE__ */ new Date()).toISOString(),
     source_dir: formatSourcePath(sourceDir),
+    public_dir: formatSourcePath(publicDir),
     config_path: formatSourcePath(configPath),
     build_pages_config_path: formatSourcePath(buildPagesConfigPath),
     preview_data_path: formatSourcePath(previewDataPath),
@@ -4209,7 +4298,8 @@ function buildPrebuildReport({
 function printPrebuildSummary(report) {
   const lines = [
     "ZeroPress build report",
-    `- Public root: ${report.source_dir}`,
+    `- Source root: ${report.source_dir}`,
+    `- Public root: ${report.public_dir}`,
     `- Markdown discovered: ${report.markdown.discovered}`,
     `- Markdown pages generated: ${report.markdown.generated_pages}`,
     `- Markdown skipped: ${report.markdown.skipped}`,
@@ -4497,6 +4587,9 @@ async function listMarkdownFiles(dir) {
       continue;
     }
     const entryPath = path.join(dir, entry.name);
+    if (isMarkdownDiscoverExcluded(entryPath)) {
+      continue;
+    }
     if (entry.isDirectory()) {
       files.push(...await listMarkdownFiles(entryPath));
       continue;
@@ -4507,6 +4600,18 @@ async function listMarkdownFiles(dir) {
   }
   return files.sort((left, right) => left.localeCompare(right));
 }
+function buildMarkdownDiscoverExcludeRoots() {
+  if (samePath(sourceDir, publicDir) || !isPathInside(sourceDir, publicDir)) {
+    return [];
+  }
+  return [publicDir];
+}
+function isMarkdownDiscoverExcluded(entryPath) {
+  return markdownDiscoverExcludeRoots.some((excludeRoot) => samePath(entryPath, excludeRoot) || isPathInside(excludeRoot, entryPath));
+}
+function samePath(firstPath, secondPath) {
+  return path.resolve(firstPath) === path.resolve(secondPath);
+}
 function shouldIgnoreMarkdownDiscoverEntry(name) {
   const basename = String(name || "");
   const lowerName = basename.toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeropress/build-pages",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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.1",
+    "@zeropress/build": "0.6.3",
     "gray-matter": "4.0.3"
   },
   "devDependencies": {

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://zeropress.dev/schemas/zeropress-build-pages.config.v0.1.schema.json",
+  "$id": "https://schemas.zeropress.dev/build-pages-config/v0.1/schema.json",
   "title": "ZeroPress Build Pages Config v0.1",
   "description": "Optional source-directory configuration for @zeropress/build-pages workflows.",
   "markdownDescription": "Optional source-directory configuration for `@zeropress/build-pages` workflows.",
@@ -50,12 +50,27 @@
           "description": "Canonical site URL. Use an empty string or omit this field for local builds without canonical output.",
           "markdownDescription": "Canonical site URL. Use an empty string or omit this field for local builds without canonical output."
         },
+        "logo": {
+          "$ref": "#/$defs/siteLogo"
+        },
+        "locale": {
+          "type": "string",
+          "minLength": 2,
+          "description": "Site locale used for generated preview-data language metadata, such as html lang and feed language.",
+          "markdownDescription": "Site locale used for generated preview-data language metadata, such as HTML `lang` and feed language."
+        },
         "expose_generator": {
           "type": "boolean",
           "default": true,
           "description": "Whether generated HTML should expose the ZeroPress generator meta tag. Set false for white-label sites.",
           "markdownDescription": "Whether generated HTML should expose `<meta name=\"generator\" content=\"ZeroPress\">`. Set `false` for white-label sites."
         },
+        "search": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether native ZeroPress search should be enabled when the selected theme supports search UI. Set false to omit native search artifacts and hide theme search UI.",
+          "markdownDescription": "Whether native ZeroPress search should be enabled when the selected theme supports search UI. Set `false` to omit native search artifacts and hide theme search UI."
+        },
         "indexing": {
           "type": "boolean",
           "default": true,
@@ -64,6 +79,29 @@
         },
         "footer": {
           "$ref": "#/$defs/siteFooter"
+        },
+        "meta": {
+          "$ref": "#/$defs/previewMeta"
+        }
+      }
+    },
+    "siteLogo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["src"],
+      "description": "Optional site logo data copied into generated preview-data.",
+      "markdownDescription": "Optional site logo data copied into generated preview-data.",
+      "properties": {
+        "src": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Logo URL or safe relative path.",
+          "markdownDescription": "Logo URL or safe relative path."
+        },
+        "alt": {
+          "type": "string",
+          "description": "Optional logo alternative text. Themes may fall back to site.title when omitted.",
+          "markdownDescription": "Optional logo alternative text. Themes may fall back to `site.title` when omitted."
         }
       }
     },
@@ -285,14 +323,23 @@
   },
   "examples": [
     {
-      "$schema": "https://zeropress.dev/schemas/zeropress-build-pages.config.v0.1.schema.json",
+      "$schema": "https://schemas.zeropress.dev/build-pages-config/v0.1/schema.json",
       "version": "0.1",
       "site": {
         "title": "ZeroPress Public Docs",
         "description": "Public documentation.",
         "url": "https://zeropress.dev",
+        "logo": {
+          "src": "/logo.svg",
+          "alt": "ZeroPress Public Docs"
+        },
+        "locale": "en-US",
         "expose_generator": true,
-        "indexing": true
+        "search": true,
+        "indexing": true,
+        "meta": {
+          "issue": "Spring 2026"
+        }
       },
       "front_page": {
         "type": "markdown"

package/src/action.js

@@ -2,6 +2,7 @@ import { runBuildPages } from './index.js';
 
 const options = {
   source: input('source') || './docs',
+  publicDir: input('public-dir'),
   destination: input('destination') || './_site',
   theme: input('theme') || 'docs',
   themePath: input('theme-path'),

package/src/index.js

@@ -39,6 +39,8 @@ export async function runBuildPages(options) {
   const cwd = path.resolve(options.cwd || process.cwd());
   const copyMarkdownSource = options.copyMarkdownSource !== false;
   const sourceDir = path.resolve(cwd, options.source);
+  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 stagingDir = path.join(cwd, STAGING_DIR);
@@ -48,18 +50,23 @@ export async function runBuildPages(options) {
   assertBuildPagesPathLayout({
     cwd,
     sourceDir,
+    publicDir,
+    publicDirExplicit,
     destinationDir,
     themeDir,
     generatedDir,
   });
   await assertDirectory(sourceDir, 'Source directory');
+  await assertPublicDirectory(publicDir, publicDirExplicit);
+  await assertDestinationPath(destinationDir);
   await fs.rm(generatedDir, { recursive: true, force: true });
   await fs.mkdir(generatedDir, { recursive: true });
 
   const env = {
     ...process.env,
     ZEROPRESS_BUILD_PAGES_SOURCE: sourceDir,
-    ZEROPRESS_PUBLIC_DIR: sourceDir,
+    ZEROPRESS_BUILD_PAGES_PUBLIC_DIR: publicDir,
+    ZEROPRESS_PUBLIC_DIR: publicDir,
     ZEROPRESS_SKIP_UNTITLED_MARKDOWN: String(Boolean(options.skipUntitledMarkdown)),
     ZEROPRESS_COPY_MARKDOWN_SOURCE: String(copyMarkdownSource),
   };
@@ -85,10 +92,13 @@ export async function runBuildPages(options) {
   await fs.rm(destinationDir, { recursive: true, force: true });
   await fs.rm(stagingDir, { recursive: true, force: true });
   await fs.mkdir(stagingDir, { recursive: true });
-  await copyPublicStaging(sourceDir, stagingDir, {
+  await copyPublicStaging(publicDir, stagingDir, {
     excludePaths: [destinationDir, themeDir, generatedDir],
     copyMarkdownSource,
   });
+  if (copyMarkdownSource) {
+    await copySourceMarkdownFiles(sourceDir, stagingDir, previewData);
+  }
 
   const previousPublicDir = process.env.ZEROPRESS_PUBLIC_DIR;
   process.env.ZEROPRESS_PUBLIC_DIR = stagingDir;
@@ -137,6 +147,7 @@ export function parseArgs(argv) {
 
     const valueOptions = new Set([
       '--source',
+      '--public-dir',
       '--destination',
       '--theme',
       '--theme-path',
@@ -167,6 +178,7 @@ export function parseArgs(argv) {
 
   return {
     source,
+    publicDir: flags['public-dir'] || '',
     destination,
     theme: flags.theme || DEFAULT_THEME,
     themePath: flags['theme-path'] || '',
@@ -186,6 +198,7 @@ Usage:
 
 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-path <dir>            Custom ZeroPress theme directory
@@ -208,6 +221,10 @@ function resolveThemeDir(cwd, options) {
   throw new Error(`Unknown bundled theme: ${options.theme}`);
 }
 
+function hasExplicitPublicDir(options) {
+  return typeof options.publicDir === 'string' && Boolean(options.publicDir.trim());
+}
+
 async function assertDirectory(dir, label) {
   let stat;
   try {
@@ -223,7 +240,55 @@ async function assertDirectory(dir, label) {
   }
 }
 
-function assertBuildPagesPathLayout({ cwd, sourceDir, destinationDir, themeDir, generatedDir }) {
+async function assertPublicDirectory(publicDir, explicit) {
+  if (!explicit) {
+    return;
+  }
+
+  let stat;
+  try {
+    stat = await fs.lstat(publicDir);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new Error(`Public directory not found: ${publicDir}`);
+    }
+    throw error;
+  }
+
+  if (stat.isSymbolicLink()) {
+    throw new Error(`Public directory must not be a symbolic link: ${publicDir}`);
+  }
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Public path is not a directory: ${publicDir}`);
+  }
+}
+
+async function assertDestinationPath(destinationDir) {
+  let stat;
+  try {
+    stat = await fs.lstat(destinationDir);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return;
+    }
+    throw error;
+  }
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Destination path is not a directory: ${destinationDir}`);
+  }
+}
+
+function assertBuildPagesPathLayout({
+  cwd,
+  sourceDir,
+  publicDir,
+  publicDirExplicit,
+  destinationDir,
+  themeDir,
+  generatedDir,
+}) {
   if (samePath(sourceDir, cwd)) {
     throw new Error(
       'Source directory must be a dedicated content directory, not the current working directory. '
@@ -231,11 +296,36 @@ function assertBuildPagesPathLayout({ cwd, sourceDir, destinationDir, themeDir,
     );
   }
 
+  if (publicDirExplicit && samePath(publicDir, cwd)) {
+    throw new Error(
+      '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);
+  if (!samePath(publicDir, sourceDir)) {
+    assertNoPathOverlap(cwd, 'Public directory', publicDir, 'internal .zeropress working directory', generatedDir);
+    assertNoPathOverlap(cwd, 'Public directory', publicDir, 'destination directory', destinationDir);
+    assertNoPathOverlap(cwd, 'Public directory', publicDir, 'theme directory', themeDir);
+  }
   assertNoPathOverlap(cwd, 'Source directory', sourceDir, 'destination directory', destinationDir);
   assertNoPathOverlap(cwd, 'Source directory', sourceDir, 'theme directory', themeDir);
+  assertSourceIsNotInsidePublicDirectory(cwd, sourceDir, publicDir);
+}
+
+function assertSourceIsNotInsidePublicDirectory(cwd, sourceDir, publicDir) {
+  if (samePath(sourceDir, publicDir) || !isPathInside(publicDir, sourceDir)) {
+    return;
+  }
+
+  throw new Error(
+    'Source directory must not be inside the public directory. '
+    + `Source directory: ${formatPath(cwd, sourceDir)}; `
+    + `Public directory: ${formatPath(cwd, publicDir)}`,
+  );
 }
 
 function assertNoPathOverlap(cwd, firstLabel, firstPath, secondLabel, secondPath) {
@@ -282,6 +372,67 @@ async function copyPublicStaging(sourceDir, targetDir, options) {
   }
 }
 
+async function copySourceMarkdownFiles(sourceDir, targetDir, previewData) {
+  const markdownUrls = new Set();
+
+  for (const page of previewData?.content?.pages || []) {
+    const sourceMarkdownUrl = page?.meta?.source_markdown_url;
+    if (typeof sourceMarkdownUrl === 'string' && sourceMarkdownUrl) {
+      markdownUrls.add(sourceMarkdownUrl);
+    }
+  }
+
+  for (const sourceMarkdownUrl of markdownUrls) {
+    const relativePath = sourceMarkdownUrlToRelativePath(sourceMarkdownUrl);
+    if (!relativePath) {
+      continue;
+    }
+
+    const sourcePath = path.join(sourceDir, relativePath);
+    if (!isPathInside(sourceDir, sourcePath)) {
+      continue;
+    }
+
+    const targetPath = path.join(targetDir, relativePath);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.copyFile(sourcePath, targetPath);
+  }
+}
+
+function sourceMarkdownUrlToRelativePath(sourceMarkdownUrl) {
+  if (
+    !sourceMarkdownUrl.startsWith('/')
+    || sourceMarkdownUrl.includes('?')
+    || sourceMarkdownUrl.includes('#')
+  ) {
+    return '';
+  }
+
+  const rawSegments = sourceMarkdownUrl.slice(1).split('/');
+  const segments = [];
+  for (const rawSegment of rawSegments) {
+    if (!rawSegment) {
+      return '';
+    }
+
+    let segment;
+    try {
+      segment = decodeURIComponent(rawSegment);
+    } catch {
+      return '';
+    }
+
+    if (!segment || segment === '.' || segment === '..' || segment.includes('/') || segment.includes('\\')) {
+      return '';
+    }
+
+    segments.push(segment);
+  }
+
+  const relativePath = segments.join('/');
+  return relativePath.toLowerCase().endsWith('.md') ? relativePath : '';
+}
+
 function shouldIgnorePublicEntry(name) {
   const basename = String(name || '');
   const lowerName = basename.toLowerCase();