@zeropress/build-pages 0.5.1 → 0.5.4

package/src/prebuild.js

@@ -1,17 +1,21 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import matter from 'gray-matter';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = process.cwd();
-const sourceDir = resolveEnvPath(['ZEROPRESS_BUILD_PAGES_SOURCE', 'ZEROPRESS_PUBLIC_DIR'], '.');
+const sourceDir = resolveEnvPath(['ZEROPRESS_BUILD_PAGES_SOURCE'], 'docs');
 const defaultConfigPath = path.join(sourceDir, '.zeropress', 'config.json');
 const configPath = resolveOptionalEnvPath(['ZEROPRESS_BUILD_PAGES_CONFIG'], defaultConfigPath);
 const outDir = path.join(rootDir, '.zeropress');
+const buildPagesConfigPath = path.join(outDir, 'build-pages-config.json');
 const previewDataPath = path.join(outDir, 'preview-data.json');
-const prebuildReportPath = path.join(outDir, 'prebuild-report.json');
+const buildReportPath = path.join(outDir, 'build-report.json');
 const skipUntitledMarkdown = readBooleanEnv('ZEROPRESS_SKIP_UNTITLED_MARKDOWN');
 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.5.schema.json';
 
 class PrebuildMarkdownError extends Error {
   constructor(sourcePath, reason, expected = '', code = 'invalid_markdown') {
@@ -41,23 +45,43 @@ async function main() {
     normalizeFrontPageConfig(config.front_page),
     config.front_page,
   );
+  const menus = normalizeMenus(config.menus);
+  const customHtmlConfig = normalizeCustomHtmlConfig(config.custom_html);
+  const resolvedConfig = buildResolvedConfig(config, {
+    frontPageConfig,
+    menus,
+    customHtmlConfig,
+  });
   const sourceFiles = await listMarkdownFiles(sourceDir);
   const skippedMarkdown = [];
   const pageInputs = [];
 
   for (const sourcePath of sourceFiles) {
     const rawMarkdown = await fs.readFile(sourcePath, 'utf8');
-    const title = extractTitleOrSkip(rawMarkdown, sourcePath, skippedMarkdown);
+    const parsedMarkdown = parseMarkdownSource(rawMarkdown, sourcePath);
+    const frontMatterStatus = readFrontMatterStatus(parsedMarkdown.frontMatter.status, sourcePath);
+    if (frontMatterStatus !== 'published') {
+      recordSkippedMarkdown(skippedMarkdown, sourcePath, frontMatterStatus.reason);
+      if (frontMatterStatus.warning) {
+        console.warn(formatSkippedMarkdownWarning(sourcePath, frontMatterStatus.reason, frontMatterStatus.expected));
+      }
+      continue;
+    }
+
+    const frontMatter = normalizePublishedFrontMatter(parsedMarkdown.frontMatter, sourcePath);
+    const title = extractTitleOrSkip(parsedMarkdown.bodyMarkdown, sourcePath, skippedMarkdown, frontMatter.title);
     if (!title) {
       continue;
     }
 
     pageInputs.push({
       sourcePath,
-      rawMarkdown,
+      bodyMarkdown: parsedMarkdown.bodyMarkdown,
+      frontMatter,
       title,
       route: buildPageRoute(sourcePath, {
         allowRootIndex: shouldAllowRootMarkdownIndex(frontPageConfig),
+        routePath: frontMatter.path,
       }),
     });
   }
@@ -66,29 +90,30 @@ async function main() {
     pageInputs.map(({ sourcePath, route }) => [sourcePath, route]),
   );
 
-  const pages = pageInputs.map(({ sourcePath, rawMarkdown, title, route }) => ({
+  const pages = pageInputs.map(({ sourcePath, bodyMarkdown, frontMatter, title, route }) => ({
     title,
     slug: route.slug,
     path: route.path,
     meta: {
+      ...frontMatter.meta,
       source_markdown_url: buildSourceMarkdownUrl(sourcePath),
     },
-    content: rewriteMarkdownLinks(rawMarkdown, sourcePath, routeBySourcePath),
+    content: rewriteMarkdownLinks(bodyMarkdown, sourcePath, routeBySourcePath),
     document_type: 'markdown',
-    excerpt: extractExcerpt(rawMarkdown, title),
+    excerpt: frontMatter.description || extractExcerpt(bodyMarkdown, title),
     status: 'published',
   }));
 
-  const frontPageResult = await buildFrontPageData(frontPageConfig, pageInputs, config);
+  const frontPageResult = await buildFrontPageData(frontPageConfig, pageInputs, resolvedConfig);
   if (frontPageResult.page) {
     pages.push(frontPageResult.page);
   }
 
-  const site = buildSiteData(config, frontPageResult.frontPage);
-  const menus = normalizeMenus(config.menus);
-  const customHtml = await buildCustomHtmlData(config.custom_html);
+  const site = buildSiteData(resolvedConfig, frontPageResult.frontPage);
+  const customHtml = await buildCustomHtmlData(customHtmlConfig);
 
   const previewData = {
+    $schema: PREVIEW_DATA_SCHEMA_URL,
     version: '0.5',
     generator: 'zeropress-build-pages',
     generated_at: new Date().toISOString(),
@@ -108,6 +133,7 @@ async function main() {
   }
 
   await fs.mkdir(outDir, { recursive: true });
+  await fs.writeFile(buildPagesConfigPath, `${JSON.stringify(resolvedConfig, null, 2)}\n`, 'utf8');
   await fs.writeFile(previewDataPath, `${JSON.stringify(previewData, null, 2)}\n`, 'utf8');
 
   const report = buildPrebuildReport({
@@ -119,7 +145,7 @@ async function main() {
     frontPage: frontPageResult.frontPage,
     customHtml,
   });
-  await fs.writeFile(prebuildReportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  await fs.writeFile(buildReportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
 
   console.log(`Wrote ${path.relative(rootDir, previewDataPath)} with ${pages.length} pages`);
   printPrebuildSummary(report);
@@ -189,27 +215,66 @@ async function loadPrebuildConfig() {
 }
 
 function buildSiteData(config, frontPage) {
-  const configuredSite = isPlainObject(config.site) ? config.site : {};
-  const footer = normalizeFooter(configuredSite.footer);
+  const configuredSite = isPlainObject(config.site) ? config.site : normalizeSiteConfig(undefined);
 
   const site = {
-    title: readConfigString(configuredSite.title, 'ZeroPress Site'),
-    description: readConfigString(configuredSite.description, 'Documentation built with ZeroPress.'),
-    url: readEnv('ZEROPRESS_SITE_URL', readConfigString(configuredSite.url, '')),
-    mediaBaseUrl: readConfigString(configuredSite.mediaBaseUrl, ''),
-    locale: readConfigString(configuredSite.locale, 'en-US'),
-    postsPerPage: readConfigInteger(configuredSite.postsPerPage, 10),
-    dateFormat: readConfigString(configuredSite.dateFormat, 'YYYY-MM-DD'),
-    timeFormat: readConfigString(configuredSite.timeFormat, 'HH:mm'),
-    timezone: readConfigString(configuredSite.timezone, 'UTC'),
-    permalinks: normalizePermalinks(configuredSite.permalinks),
+    title: configuredSite.title,
+    description: configuredSite.description,
+    url: configuredSite.url,
+    mediaBaseUrl: '',
+    locale: 'en-US',
+    postsPerPage: 10,
+    dateFormat: 'YYYY-MM-DD',
+    timeFormat: 'HH:mm',
+    timezone: 'UTC',
+    permalinks: defaultPermalinks(),
     front_page: frontPage,
     post_index: {
       enabled: false,
     },
-    disallowComments: configuredSite.disallowComments !== false,
+    disallowComments: true,
   };
 
+  if (configuredSite.footer) {
+    site.footer = configuredSite.footer;
+  }
+
+  return site;
+}
+
+function buildResolvedConfig(config, { frontPageConfig, menus, customHtmlConfig }) {
+  const resolvedConfig = {
+    $schema: BUILD_PAGES_CONFIG_SCHEMA_URL,
+    version: '0.1',
+    site: normalizeSiteConfig(config.site),
+    front_page: frontPageConfig,
+    menus,
+  };
+
+  if (customHtmlConfig) {
+    resolvedConfig.custom_html = customHtmlConfig;
+  }
+
+  return resolvedConfig;
+}
+
+function normalizeSiteConfig(value) {
+  if (value !== undefined && !isPlainObject(value)) {
+    throw new PrebuildConfigError(
+      'site must be an object.',
+      '  "site": { "title": "My Docs", "description": "Project documentation" }',
+    );
+  }
+
+  const configuredSite = isPlainObject(value) ? value : {};
+  assertKnownConfigKeys(configuredSite, ['title', 'description', 'url', 'footer'], 'site');
+  const site = {
+    title: readConfigString(configuredSite.title, 'Documentation'),
+    description: readConfigString(configuredSite.description, 'A documentation site.'),
+    url: readEnv('ZEROPRESS_SITE_URL', readConfigString(configuredSite.url, '')),
+  };
+
+  const footer = normalizeFooter(configuredSite.footer);
   if (footer) {
     site.footer = footer;
   }
@@ -218,9 +283,13 @@ function buildSiteData(config, frontPage) {
 }
 
 function normalizeFooter(value) {
-  if (!isPlainObject(value)) {
+  if (value === undefined) {
     return undefined;
   }
+  if (!isPlainObject(value)) {
+    throw new PrebuildConfigError('site.footer must be an object.');
+  }
+  assertKnownConfigKeys(value, ['copyright_text', 'attribution'], 'site.footer');
 
   const footer = {};
   const copyrightText = readConfigString(value.copyright_text, '');
@@ -228,6 +297,15 @@ function normalizeFooter(value) {
     footer.copyright_text = copyrightText;
   }
 
+  if (value.attribution !== undefined && !isPlainObject(value.attribution)) {
+    throw new PrebuildConfigError('site.footer.attribution must be an object.');
+  }
+  if (isPlainObject(value.attribution)) {
+    assertKnownConfigKeys(value.attribution, ['enabled'], 'site.footer.attribution');
+    if (value.attribution.enabled !== undefined && typeof value.attribution.enabled !== 'boolean') {
+      throw new PrebuildConfigError('site.footer.attribution.enabled must be a boolean when provided.');
+    }
+  }
   if (isPlainObject(value.attribution) && typeof value.attribution.enabled === 'boolean') {
     footer.attribution = {
       enabled: value.attribution.enabled,
@@ -390,7 +468,7 @@ function isZeropressHtmlFile(filePath) {
   return filePath.startsWith('.zeropress/') && filePath.toLowerCase().endsWith('.html');
 }
 
-async function buildCustomHtmlData(value) {
+function normalizeCustomHtmlConfig(value) {
   if (value === undefined) {
     return undefined;
   }
@@ -408,18 +486,18 @@ async function buildCustomHtmlData(value) {
     );
   }
 
-  const customHtml = {};
+  const customHtmlConfig = {};
   if (value.head_end !== undefined) {
-    customHtml.head_end = await buildCustomHtmlSlotData(value.head_end, 'custom_html.head_end');
+    customHtmlConfig.head_end = normalizeCustomHtmlSlotConfig(value.head_end, 'custom_html.head_end');
   }
   if (value.body_end !== undefined) {
-    customHtml.body_end = await buildCustomHtmlSlotData(value.body_end, 'custom_html.body_end');
+    customHtmlConfig.body_end = normalizeCustomHtmlSlotConfig(value.body_end, 'custom_html.body_end');
   }
 
-  return customHtml;
+  return customHtmlConfig;
 }
 
-async function buildCustomHtmlSlotData(value, pathLabel) {
+function normalizeCustomHtmlSlotConfig(value, pathLabel) {
   if (!isPlainObject(value)) {
     throw new PrebuildConfigError(`${pathLabel} must be an object.`);
   }
@@ -439,7 +517,29 @@ async function buildCustomHtmlSlotData(value, pathLabel) {
     );
   }
 
-  const sourcePath = resolveConfiguredSourceFile(file, '.html', `${pathLabel}.file`);
+  return {
+    file,
+  };
+}
+
+async function buildCustomHtmlData(config) {
+  if (!config) {
+    return undefined;
+  }
+
+  const customHtml = {};
+  if (config.head_end) {
+    customHtml.head_end = await buildCustomHtmlSlotData(config.head_end, 'custom_html.head_end');
+  }
+  if (config.body_end) {
+    customHtml.body_end = await buildCustomHtmlSlotData(config.body_end, 'custom_html.body_end');
+  }
+
+  return customHtml;
+}
+
+async function buildCustomHtmlSlotData(slotConfig, pathLabel) {
+  const sourcePath = resolveConfiguredSourceFile(slotConfig.file, '.html', `${pathLabel}.file`);
   return {
     content: await readRequiredSourceFile(sourcePath, `${pathLabel}.file`),
   };
@@ -549,13 +649,13 @@ function isPathInside(parentPath, childPath) {
   return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
 }
 
-function normalizePermalinks(value) {
+function defaultPermalinks() {
   return {
-    output_style: readConfigString(value?.output_style, 'html-extension'),
-    posts: readConfigString(value?.posts, '/posts/:slug/'),
-    pages: readConfigString(value?.pages, '/:slug/'),
-    categories: readConfigString(value?.categories, '/categories/:slug/'),
-    tags: readConfigString(value?.tags, '/tags/:slug/'),
+    output_style: 'html-extension',
+    posts: '/posts/:slug/',
+    pages: '/:slug/',
+    categories: '/categories/:slug/',
+    tags: '/tags/:slug/',
   };
 }
 
@@ -629,8 +729,9 @@ function buildPrebuildReport({
     generated_at: new Date().toISOString(),
     source_dir: formatSourcePath(sourceDir),
     config_path: formatSourcePath(configPath),
+    build_pages_config_path: formatSourcePath(buildPagesConfigPath),
     preview_data_path: formatSourcePath(previewDataPath),
-    report_path: formatSourcePath(prebuildReportPath),
+    report_path: formatSourcePath(buildReportPath),
     skip_untitled_markdown: skipUntitledMarkdown,
     markdown: {
       discovered: sourceFiles.length,
@@ -651,7 +752,7 @@ function buildPrebuildReport({
 
 function printPrebuildSummary(report) {
   const lines = [
-    'ZeroPress prebuild report',
+    'ZeroPress build report',
     `- Public root: ${report.source_dir}`,
     `- Markdown discovered: ${report.markdown.discovered}`,
     `- Markdown pages generated: ${report.markdown.generated_pages}`,
@@ -659,6 +760,7 @@ function printPrebuildSummary(report) {
     `- Total preview pages: ${report.pages.total}`,
     `- Front page: ${formatFrontPageSummary(report.front_page)}`,
     `- Custom HTML slots: ${report.custom_html.length ? report.custom_html.join(', ') : 'none'}`,
+    `- Resolved config: ${report.build_pages_config_path}`,
     `- Report: ${report.report_path}`,
   ];
 
@@ -680,7 +782,171 @@ function formatFrontPageSummary(frontPageReport) {
   return `html ${config.file} -> / (${previewData.page_slug})`;
 }
 
-function extractTitleOrSkip(markdown, sourcePath, skippedMarkdown) {
+function parseMarkdownSource(rawMarkdown, sourcePath) {
+  try {
+    const parsed = matter(rawMarkdown);
+    if (!isPlainObject(parsed.data)) {
+      throw new PrebuildMarkdownError(
+        sourcePath,
+        'front matter must be a YAML object.',
+      );
+    }
+
+    return {
+      bodyMarkdown: parsed.content,
+      frontMatter: parsed.data,
+    };
+  } catch (error) {
+    if (error instanceof PrebuildMarkdownError) {
+      throw error;
+    }
+
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      `invalid YAML front matter: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+function readFrontMatterStatus(value, sourcePath) {
+  if (value === undefined || value === 'published') {
+    return 'published';
+  }
+  if (value === 'draft') {
+    return {
+      reason: 'front matter status is "draft".',
+    };
+  }
+
+  return {
+    reason: `unsupported front matter status ${formatFrontMatterValue(value)}.`,
+    expected: 'Expected status: published or draft.',
+    warning: true,
+  };
+}
+
+function normalizePublishedFrontMatter(frontMatter, sourcePath) {
+  return {
+    title: normalizeFrontMatterTitle(frontMatter.title, sourcePath),
+    description: normalizeFrontMatterDescription(frontMatter.description, sourcePath),
+    path: normalizeFrontMatterRoutePath(frontMatter.path, sourcePath),
+    meta: normalizeFrontMatterMeta(frontMatter.meta, sourcePath),
+  };
+}
+
+function normalizeFrontMatterTitle(value, sourcePath) {
+  if (value === undefined) {
+    return '';
+  }
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      'front matter title must be a non-empty string when provided.',
+    );
+  }
+
+  return value.trim();
+}
+
+function normalizeFrontMatterDescription(value, sourcePath) {
+  if (value === undefined) {
+    return '';
+  }
+  if (typeof value !== 'string') {
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      'front matter description must be a string when provided.',
+    );
+  }
+
+  return value.trim();
+}
+
+function normalizeFrontMatterRoutePath(value, sourcePath) {
+  if (value === undefined) {
+    return '';
+  }
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      'front matter path must be a non-empty string when provided.',
+    );
+  }
+
+  const routePath = value.trim();
+  const segments = routePath.split('/');
+  if (
+    routePath.startsWith('/')
+    || routePath.endsWith('/')
+    || routePath.includes('\\')
+    || routePath.includes('?')
+    || routePath.includes('#')
+    || segments.some((segment) => !isSafeRoutePathSegment(segment))
+  ) {
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      'front matter path must be a safe generated route path.',
+      '  path: guides/install\n  path: spec/preview-data-v0.5',
+    );
+  }
+
+  return routePath;
+}
+
+function isSafeRoutePathSegment(segment) {
+  return (
+    /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(segment)
+    && !segment.includes('..')
+  );
+}
+
+function normalizeFrontMatterMeta(value, sourcePath) {
+  if (value === undefined) {
+    return {};
+  }
+  if (!isPlainObject(value)) {
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      'front matter meta must be an object when provided.',
+    );
+  }
+
+  const meta = {};
+  for (const [key, metaValue] of Object.entries(value)) {
+    if (!isPreviewMetaValue(metaValue)) {
+      throw new PrebuildMarkdownError(
+        sourcePath,
+        `front matter meta.${key} must be a string, number, boolean, or null.`,
+      );
+    }
+    meta[key] = metaValue;
+  }
+
+  return meta;
+}
+
+function isPreviewMetaValue(value) {
+  return (
+    value === null
+    || typeof value === 'string'
+    || typeof value === 'number'
+    || typeof value === 'boolean'
+  );
+}
+
+function formatFrontMatterValue(value) {
+  if (typeof value === 'string') {
+    return `"${value}"`;
+  }
+  const serialized = JSON.stringify(value);
+  return serialized === undefined ? String(value) : serialized;
+}
+
+function extractTitleOrSkip(markdown, sourcePath, skippedMarkdown, frontMatterTitle = '') {
+  if (frontMatterTitle) {
+    return frontMatterTitle;
+  }
+
   try {
     return extractTitle(markdown, sourcePath);
   } catch (error) {
@@ -689,11 +955,8 @@ function extractTitleOrSkip(markdown, sourcePath, skippedMarkdown) {
       && error instanceof PrebuildMarkdownError
       && error.code === 'untitled_markdown'
     ) {
-      console.warn(formatSkippedUntitledMarkdownWarning(error));
-      skippedMarkdown.push({
-        file: formatSourcePath(error.sourcePath),
-        reason: error.reason,
-      });
+      console.warn(formatSkippedMarkdownWarning(error.sourcePath, error.reason, '', 'Skipped untitled Markdown'));
+      recordSkippedMarkdown(skippedMarkdown, error.sourcePath, error.reason);
       return '';
     }
 
@@ -701,12 +964,23 @@ function extractTitleOrSkip(markdown, sourcePath, skippedMarkdown) {
   }
 }
 
-function formatSkippedUntitledMarkdownWarning(error) {
-  return [
-    `[zeropress-build-pages] Skipped untitled Markdown: ${formatSourcePath(error.sourcePath)}`,
-    `Reason: ${error.reason}`,
-    'This file was not added to preview-data pages.',
-  ].join('\n');
+function recordSkippedMarkdown(skippedMarkdown, sourcePath, reason) {
+  skippedMarkdown.push({
+    file: formatSourcePath(sourcePath),
+    reason,
+  });
+}
+
+function formatSkippedMarkdownWarning(sourcePath, reason, expected = '', label = 'Skipped Markdown') {
+  const lines = [
+    `[zeropress-build-pages] ${label}: ${formatSourcePath(sourcePath)}`,
+    `Reason: ${reason}`,
+  ];
+  if (expected) {
+    lines.push(expected);
+  }
+  lines.push('This file was not added to preview-data pages.');
+  return lines.join('\n');
 }
 
 async function listMarkdownFiles(dir) {
@@ -780,6 +1054,17 @@ function buildHtmlPageRoute(sourcePath, options = {}) {
 }
 
 function buildRoutePath(relativeSourcePath, sourcePath, options = {}) {
+  if (options.routePath) {
+    if (options.routePath === 'index' && !options.allowRootIndex) {
+      throw new PrebuildMarkdownError(
+        sourcePath,
+        'front matter path "index" is reserved for the front page.',
+        '  path: docs/index\n  path: guide',
+      );
+    }
+    return options.routePath;
+  }
+
   const extensionPattern = options.extensionPattern || /\.md$/i;
   const withoutExtension = relativeSourcePath.replace(extensionPattern, '').toLowerCase();
   const segments = withoutExtension