@zeropress/build-pages 0.5.6 → 0.6.2

package/src/prebuild.js

@@ -6,6 +6,7 @@ import matter from 'gray-matter';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 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');
@@ -16,7 +17,13 @@ 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.5.schema.json';
+const PREVIEW_DATA_SCHEMA_URL = 'https://zeropress.dev/schemas/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 markdownDiscoverExcludeRoots = buildMarkdownDiscoverExcludeRoots();
 
 class PrebuildMarkdownError extends Error {
   constructor(sourcePath, reason, expected = '', code = 'invalid_markdown') {
@@ -99,6 +106,8 @@ async function main() {
       ...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),
@@ -115,7 +124,7 @@ async function main() {
 
   const previewData = {
     $schema: PREVIEW_DATA_SCHEMA_URL,
-    version: '0.5',
+    version: '0.6',
     generator: 'zeropress-build-pages',
     generated_at: new Date().toISOString(),
     site,
@@ -222,18 +231,21 @@ function buildSiteData(config, frontPage) {
     title: configuredSite.title,
     description: configuredSite.description,
     url: configuredSite.url,
-    mediaBaseUrl: '',
+    media_base_url: '',
     locale: 'en-US',
-    postsPerPage: 10,
-    dateFormat: 'YYYY-MM-DD',
-    timeFormat: 'HH:mm',
+    posts_per_page: 10,
+    datetime_display: 'static',
+    date_style: 'medium',
+    time_style: 'none',
     timezone: 'UTC',
     permalinks: defaultPermalinks(),
     front_page: frontPage,
     post_index: {
       enabled: false,
     },
-    disallowComments: true,
+    disallow_comments: true,
+    expose_generator: configuredSite.expose_generator !== false,
+    search: configuredSite.search !== false,
     indexing: configuredSite.indexing !== false,
   };
 
@@ -269,11 +281,13 @@ function normalizeSiteConfig(value) {
   }
 
   const configuredSite = isPlainObject(value) ? value : {};
-  assertKnownConfigKeys(configuredSite, ['title', 'description', 'url', 'indexing', 'footer'], 'site');
+  assertKnownConfigKeys(configuredSite, ['title', 'description', 'url', 'expose_generator', 'search', 'indexing', 'footer'], 'site');
   const site = {
     title: readConfigString(configuredSite.title, 'Documentation'),
     description: readConfigString(configuredSite.description, 'A documentation site.'),
     url: readEnv('ZEROPRESS_SITE_URL', readConfigString(configuredSite.url, '')),
+    expose_generator: readConfigBoolean(configuredSite.expose_generator, true, 'site.expose_generator'),
+    search: readConfigBoolean(configuredSite.search, true, 'site.search'),
     indexing: readConfigBoolean(configuredSite.indexing, true, 'site.indexing'),
   };
 
@@ -300,19 +314,11 @@ 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 (value.attribution !== undefined) {
+    if (typeof value.attribution !== 'boolean') {
+      throw new PrebuildConfigError('site.footer.attribution must be a boolean when provided.');
     }
-  }
-  if (isPlainObject(value.attribution) && typeof value.attribution.enabled === 'boolean') {
-    footer.attribution = {
-      enabled: value.attribution.enabled,
-    };
+    footer.attribution = value.attribution;
   }
 
   return Object.keys(footer).length ? footer : undefined;
@@ -712,12 +718,29 @@ function normalizeMenuItem(item, pathLabel) {
     url,
     type: readConfigString(item.type, 'custom'),
     target: readConfigString(item.target, '_self'),
+    ...(item.meta !== undefined ? { meta: normalizeMenuItemMeta(item.meta, `${pathLabel}.meta`) } : {}),
     children: Array.isArray(item.children)
       ? item.children.map((child, index) => normalizeMenuItem(child, `${pathLabel}.children[${index}]`))
       : [],
   };
 }
 
+function normalizeMenuItemMeta(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 defaultMenus() {
   return {
     primary: {
@@ -741,6 +764,7 @@ function buildPrebuildReport({
   return {
     generated_at: 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),
@@ -767,7 +791,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}`,
@@ -844,7 +869,9 @@ function normalizePublishedFrontMatter(frontMatter, sourcePath) {
     title: normalizeFrontMatterTitle(frontMatter.title, sourcePath),
     description: normalizeFrontMatterDescription(frontMatter.description, sourcePath),
     path: normalizeFrontMatterRoutePath(frontMatter.path, sourcePath),
+    discoverability: normalizeFrontMatterDiscoverability(frontMatter.discoverability, sourcePath),
     meta: normalizeFrontMatterMeta(frontMatter.meta, sourcePath),
+    data: normalizeFrontMatterData(frontMatter.data, sourcePath),
   };
 }
 
@@ -900,13 +927,28 @@ function normalizeFrontMatterRoutePath(value, sourcePath) {
     throw new PrebuildMarkdownError(
       sourcePath,
       'front matter path must be a safe generated route path.',
-      '  path: guides/install\n  path: spec/preview-data-v0.5',
+      '  path: guides/install\n  path: spec/preview-data-v0.6',
     );
   }
 
   return routePath;
 }
 
+function normalizeFrontMatterDiscoverability(value, sourcePath) {
+  if (value === undefined) {
+    return 'default';
+  }
+  if (typeof value === 'string' && FRONT_MATTER_DISCOVERABILITY_VALUES.has(value)) {
+    return value;
+  }
+
+  throw new PrebuildMarkdownError(
+    sourcePath,
+    `front matter discoverability must be one of: ${Array.from(FRONT_MATTER_DISCOVERABILITY_VALUES).join(', ')}.`,
+    '  discoverability: default\n  discoverability: noindex\n  discoverability: delist',
+  );
+}
+
 function isSafeRoutePathSegment(segment) {
   return (
     /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(segment)
@@ -943,11 +985,102 @@ function isPreviewMetaValue(value) {
   return (
     value === null
     || typeof value === 'string'
-    || typeof value === 'number'
+    || (typeof value === 'number' && Number.isFinite(value))
     || typeof value === 'boolean'
   );
 }
 
+function normalizeFrontMatterData(value, sourcePath) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!isPlainObject(value)) {
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      'front matter data must be an object when provided.',
+    );
+  }
+
+  validateFrontMatterDataObject(value, sourcePath, 'data', 0);
+  return value;
+}
+
+function validateFrontMatterDataValue(value, sourcePath, pathLabel, depth) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+    return;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new PrebuildMarkdownError(
+        sourcePath,
+        `front matter ${pathLabel} must be a finite number.`,
+      );
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    validateFrontMatterDataArray(value, sourcePath, pathLabel, depth);
+    return;
+  }
+  if (isPlainObject(value)) {
+    validateFrontMatterDataObject(value, sourcePath, pathLabel, depth);
+    return;
+  }
+
+  throw new PrebuildMarkdownError(
+    sourcePath,
+    `front matter ${pathLabel} must be JSON-safe structured data.`,
+  );
+}
+
+function validateFrontMatterDataObject(object, sourcePath, pathLabel, depth) {
+  if (depth > FRONT_MATTER_DATA_MAX_DEPTH) {
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      `front matter ${pathLabel} nesting must not exceed ${FRONT_MATTER_DATA_MAX_DEPTH} container levels.`,
+    );
+  }
+
+  const entries = Object.entries(object);
+  if (entries.length > FRONT_MATTER_DATA_MAX_KEYS) {
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      `front matter ${pathLabel} must not contain more than ${FRONT_MATTER_DATA_MAX_KEYS} keys.`,
+    );
+  }
+
+  for (const [key, dataValue] of entries) {
+    const childLabel = `${pathLabel}.${key}`;
+    if (!FRONT_MATTER_DATA_KEY_PATTERN.test(key)) {
+      throw new PrebuildMarkdownError(
+        sourcePath,
+        `front matter ${childLabel} uses an invalid key.`,
+      );
+    }
+    validateFrontMatterDataValue(dataValue, sourcePath, childLabel, depth + 1);
+  }
+}
+
+function validateFrontMatterDataArray(array, sourcePath, pathLabel, depth) {
+  if (depth > FRONT_MATTER_DATA_MAX_DEPTH) {
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      `front matter ${pathLabel} nesting must not exceed ${FRONT_MATTER_DATA_MAX_DEPTH} container levels.`,
+    );
+  }
+
+  if (array.length > FRONT_MATTER_DATA_MAX_ARRAY_LENGTH) {
+    throw new PrebuildMarkdownError(
+      sourcePath,
+      `front matter ${pathLabel} must not contain more than ${FRONT_MATTER_DATA_MAX_ARRAY_LENGTH} items.`,
+    );
+  }
+
+  array.forEach((dataValue, index) => {
+    validateFrontMatterDataValue(dataValue, sourcePath, `${pathLabel}[${index}]`, depth + 1);
+  });
+}
+
 function formatFrontMatterValue(value) {
   if (typeof value === 'string') {
     return `"${value}"`;
@@ -1007,6 +1140,10 @@ async function listMarkdownFiles(dir) {
     }
 
     const entryPath = path.join(dir, entry.name);
+    if (isMarkdownDiscoverExcluded(entryPath)) {
+      continue;
+    }
+
     if (entry.isDirectory()) {
       files.push(...await listMarkdownFiles(entryPath));
       continue;
@@ -1020,6 +1157,24 @@ 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/themes/docs/assets/style.css

@@ -12,6 +12,15 @@
   --prose-ink: #344054;
   --pre-bg: #101828;
   --pre-ink: #f8fafc;
+  --syntax-comment: #98a2b3;
+  --syntax-keyword: #f472b6;
+  --syntax-title: #93c5fd;
+  --syntax-string: #86efac;
+  --syntax-number: #fbbf24;
+  --syntax-attr: #67e8f9;
+  --syntax-built-in: #c4b5fd;
+  --syntax-deletion: #fca5a5;
+  --syntax-addition: #bbf7d0;
   --button-ink: #ffffff;
   --alert-note: #2563eb;
   --alert-tip: #059669;
@@ -99,12 +108,31 @@ a {
   gap: 1.5rem;
 }
 
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 .brand {
   color: var(--ink);
   font-weight: 750;
   text-decoration: none;
 }
 
+.site-header__actions {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 1rem;
+  min-width: 0;
+}
+
 .site-nav ul {
   list-style: none;
   margin: 0;
@@ -129,6 +157,109 @@ a {
   color: var(--accent);
 }
 
+.site-search {
+  position: relative;
+  width: min(22rem, 34vw);
+}
+
+.site-search__form {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+}
+
+.site-search__input {
+  min-width: 0;
+  width: 100%;
+  height: 2.35rem;
+  padding: 0 0.75rem;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  background: var(--surface);
+  color: var(--ink);
+  font: inherit;
+  font-size: 0.92rem;
+}
+
+.site-search__input:focus {
+  border-color: var(--accent);
+  outline: 2px solid color-mix(in srgb, var(--accent) 22%, transparent);
+  outline-offset: 1px;
+}
+
+.site-search__button {
+  height: 2.35rem;
+  padding: 0 0.75rem;
+  border: 0;
+  border-radius: 6px;
+  background: var(--accent);
+  color: var(--button-ink);
+  font: inherit;
+  font-size: 0.88rem;
+  font-weight: 750;
+  cursor: pointer;
+}
+
+.site-search__panel {
+  position: absolute;
+  top: calc(100% + 0.55rem);
+  right: 0;
+  width: min(31rem, calc(100vw - 2rem));
+  max-height: min(31rem, calc(100vh - 6rem));
+  overflow: auto;
+  padding: 0.85rem;
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: var(--surface);
+  box-shadow: 0 20px 45px rgb(15 23 42 / 18%);
+}
+
+.site-search__status {
+  margin: 0 0 0.75rem;
+  color: var(--muted);
+  font-size: 0.86rem;
+}
+
+.site-search__results {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.site-search__results li + li {
+  margin-top: 0.65rem;
+  padding-top: 0.65rem;
+  border-top: 1px solid var(--line);
+}
+
+.site-search__results a {
+  display: inline-block;
+  color: var(--ink);
+  font-weight: 750;
+  text-decoration: none;
+}
+
+.site-search__results a:hover {
+  color: var(--accent);
+  text-decoration: underline;
+}
+
+.site-search__results span {
+  display: block;
+  margin-top: 0.1rem;
+  color: var(--accent);
+  font-size: 0.75rem;
+  font-weight: 750;
+  text-transform: uppercase;
+}
+
+.site-search__results p {
+  margin: 0.25rem 0 0;
+  color: var(--muted);
+  font-size: 0.88rem;
+  line-height: 1.45;
+}
+
 .hero {
   background: var(--surface);
   border-bottom: 1px solid var(--line);
@@ -372,6 +503,71 @@ h1 {
   padding: 0;
 }
 
+.prose pre code.hljs {
+  color: var(--pre-ink);
+}
+
+.prose .hljs-comment,
+.prose .hljs-quote {
+  color: var(--syntax-comment);
+  font-style: italic;
+}
+
+.prose .hljs-keyword,
+.prose .hljs-selector-tag,
+.prose .hljs-subst {
+  color: var(--syntax-keyword);
+}
+
+.prose .hljs-title,
+.prose .hljs-section,
+.prose .hljs-name,
+.prose .hljs-selector-id,
+.prose .hljs-selector-class {
+  color: var(--syntax-title);
+}
+
+.prose .hljs-string,
+.prose .hljs-regexp,
+.prose .hljs-symbol,
+.prose .hljs-bullet {
+  color: var(--syntax-string);
+}
+
+.prose .hljs-number,
+.prose .hljs-literal {
+  color: var(--syntax-number);
+}
+
+.prose .hljs-attr,
+.prose .hljs-attribute,
+.prose .hljs-variable,
+.prose .hljs-template-variable {
+  color: var(--syntax-attr);
+}
+
+.prose .hljs-built_in,
+.prose .hljs-type,
+.prose .hljs-class .hljs-title {
+  color: var(--syntax-built-in);
+}
+
+.prose .hljs-deletion {
+  color: var(--syntax-deletion);
+}
+
+.prose .hljs-addition {
+  color: var(--syntax-addition);
+}
+
+.prose .hljs-emphasis {
+  font-style: italic;
+}
+
+.prose .hljs-strong {
+  font-weight: 800;
+}
+
 .prose table {
   display: block;
   width: 100%;
@@ -544,10 +740,26 @@ h1, h2, h3, h4, h5, h6 {
     padding: 1rem 0;
   }
 
+  .site-header__actions {
+    width: 100%;
+    align-items: stretch;
+    flex-direction: column;
+  }
+
   .site-nav ul {
     justify-content: flex-start;
   }
 
+  .site-search {
+    width: 100%;
+  }
+
+  .site-search__panel {
+    left: 0;
+    right: auto;
+    width: 100%;
+  }
+
   .docs-grid,
   .npm-links,
   .doc-layout,

package/themes/docs/assets/theme.js

@@ -0,0 +1,121 @@
+const searchRoot = document.querySelector('[data-site-search]');
+
+if (searchRoot) {
+  const form = searchRoot.querySelector('[data-site-search-form]');
+  const input = searchRoot.querySelector('[data-site-search-input]');
+  const panel = searchRoot.querySelector('[data-site-search-panel]');
+  const status = searchRoot.querySelector('[data-site-search-status]');
+  const resultsList = searchRoot.querySelector('[data-site-search-results]');
+  let searchApiPromise;
+  let debounceTimer;
+  let requestId = 0;
+
+  const loadSearchApi = () => {
+    searchApiPromise ||= import('/_zeropress/search.js');
+    return searchApiPromise;
+  };
+
+  const clearResults = () => {
+    resultsList.replaceChildren();
+  };
+
+  const showPanel = () => {
+    panel.hidden = false;
+  };
+
+  const hidePanel = () => {
+    panel.hidden = true;
+  };
+
+  const setStatus = (message) => {
+    status.textContent = message;
+  };
+
+  const renderResults = async (items) => {
+    clearResults();
+    if (!items.length) {
+      setStatus('No results found.');
+      return;
+    }
+
+    setStatus(`${items.length} result${items.length === 1 ? '' : 's'} found.`);
+    const fragment = document.createDocumentFragment();
+
+    for (const item of items) {
+      const data = await item.data();
+      const title = data.meta?.title || data.url;
+      const excerpt = data.plain_excerpt || data.excerpt || '';
+      const listItem = document.createElement('li');
+      const link = document.createElement('a');
+      const meta = document.createElement('span');
+      const summary = document.createElement('p');
+
+      link.href = data.url;
+      link.textContent = title;
+      meta.textContent = data.meta?.type || 'page';
+      summary.textContent = excerpt;
+
+      listItem.append(link, meta, summary);
+      fragment.append(listItem);
+    }
+
+    resultsList.append(fragment);
+  };
+
+  const runSearch = async () => {
+    const query = input.value.trim();
+    const currentRequest = ++requestId;
+    showPanel();
+
+    if (query.length < 2) {
+      clearResults();
+      setStatus('Type at least two characters.');
+      return;
+    }
+
+    setStatus('Searching...');
+    clearResults();
+
+    try {
+      const searchApi = await loadSearchApi();
+      const response = await searchApi.search(query, { limit: 8 });
+      if (currentRequest === requestId) {
+        await renderResults(response.results || []);
+      }
+    } catch {
+      if (currentRequest === requestId) {
+        clearResults();
+        setStatus('Search is not available for this build.');
+      }
+    }
+  };
+
+  input.addEventListener('input', () => {
+    window.clearTimeout(debounceTimer);
+    debounceTimer = window.setTimeout(runSearch, 160);
+  });
+
+  input.addEventListener('focus', () => {
+    if (input.value.trim()) {
+      showPanel();
+    }
+  });
+
+  form.addEventListener('submit', (event) => {
+    event.preventDefault();
+    runSearch();
+  });
+
+  document.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape') {
+      hidePanel();
+      input.blur();
+    }
+  });
+
+  document.addEventListener('click', (event) => {
+    if (!searchRoot.contains(event.target)) {
+      hidePanel();
+    }
+  });
+}