@zeropress/build-pages 0.6.1 → 0.6.2

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

@@ -56,6 +56,12 @@
           "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,
@@ -292,6 +298,7 @@
         "description": "Public documentation.",
         "url": "https://zeropress.dev",
         "expose_generator": true,
+        "search": true,
         "indexing": true
       },
       "front_page": {

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();

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');
@@ -22,6 +23,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 markdownDiscoverExcludeRoots = buildMarkdownDiscoverExcludeRoots();
 
 class PrebuildMarkdownError extends Error {
   constructor(sourcePath, reason, expected = '', code = 'invalid_markdown') {
@@ -243,6 +245,7 @@ function buildSiteData(config, frontPage) {
     },
     disallow_comments: true,
     expose_generator: configuredSite.expose_generator !== false,
+    search: configuredSite.search !== false,
     indexing: configuredSite.indexing !== false,
   };
 
@@ -278,12 +281,13 @@ function normalizeSiteConfig(value) {
   }
 
   const configuredSite = isPlainObject(value) ? value : {};
-  assertKnownConfigKeys(configuredSite, ['title', 'description', 'url', 'expose_generator', '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'),
   };
 
@@ -760,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),
@@ -786,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}`,
@@ -1134,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;
@@ -1147,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,