@pruddiman/mdmirror 0.1.0

package/README.md

@@ -0,0 +1 @@
+# mdmirror

package/dist/build/builder.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Static site builder.
+ * Writes all rendered HTML pages and assets to an output directory.
+ */
+import type { Document, NavigationTree } from "../types.js";
+export interface BuildOptions {
+    /** All processed documents */
+    documents: Document[];
+    /** Built navigation tree */
+    navigationTree: NavigationTree;
+    /** CSS stylesheet content */
+    stylesheet: string;
+    /** Output directory path */
+    outputDir: string;
+    /** Navigation JS content */
+    navigationScript?: string;
+    /** URL path to the Mermaid UMD bundle */
+    mermaidBundleSrc?: string;
+    /** Inline script to initialize Mermaid after the bundle loads */
+    mermaidInitScript?: string;
+    /** Inline search script (injected per-page) */
+    searchScript?: string;
+    /** Base URL for canonical links and sitemap (e.g. "https://example.com") */
+    baseUrl?: string;
+}
+export interface BuildResult {
+    /** Number of pages written */
+    pageCount: number;
+    /** Total output size in bytes */
+    totalSize: number;
+    /** Absolute path of the output directory */
+    outputPath: string;
+}
+/**
+ * Build the static site output.
+ */
+export declare function buildSite(options: BuildOptions): Promise<BuildResult>;
+/**
+ * Format bytes into a human-readable string.
+ */
+export declare function formatSize(bytes: number): string;

package/dist/build/builder.js

@@ -0,0 +1,108 @@
+/**
+ * Static site builder.
+ * Writes all rendered HTML pages and assets to an output directory.
+ */
+import { mkdir, writeFile, copyFile, stat as fsStat } from "node:fs/promises";
+import { resolve, dirname, join } from "node:path";
+import { renderLayout } from "../theme/layout.js";
+import { buildSearchIndex } from "../search/index.js";
+/**
+ * Build the static site output.
+ */
+export async function buildSite(options) {
+    const { documents, navigationTree, stylesheet, outputDir, navigationScript, mermaidBundleSrc, mermaidInitScript, searchScript, baseUrl, } = options;
+    const outputPath = resolve(outputDir);
+    let totalSize = 0;
+    // Create output directory
+    try {
+        await mkdir(outputPath, { recursive: true });
+    }
+    catch (error) {
+        throw new Error(`Cannot create output directory: ${outputPath} (${error instanceof Error ? error.message : "permission denied"})`, { cause: error });
+    }
+    // Create assets directory
+    const assetsDir = join(outputPath, "assets");
+    await mkdir(assetsDir, { recursive: true });
+    const cssContent = stylesheet;
+    // Write search index
+    const searchIndex = buildSearchIndex(documents);
+    const searchJson = JSON.stringify(searchIndex);
+    await writeFile(join(assetsDir, "search.json"), searchJson, "utf-8");
+    totalSize += Buffer.byteLength(searchJson, "utf-8");
+    // Write navigation script if provided
+    if (navigationScript) {
+        await writeFile(join(assetsDir, "main.js"), navigationScript, "utf-8");
+        totalSize += Buffer.byteLength(navigationScript, "utf-8");
+    }
+    // Copy Mermaid JS bundle if available
+    try {
+        const mermaidSrc = resolve("node_modules/mermaid/dist/mermaid.min.js");
+        await fsStat(mermaidSrc);
+        await copyFile(mermaidSrc, join(assetsDir, "mermaid.min.js"));
+        const mermaidSize = (await fsStat(join(assetsDir, "mermaid.min.js"))).size;
+        totalSize += mermaidSize;
+    }
+    catch {
+        console.warn("Warning: Mermaid bundle not found — diagram pages may not render correctly");
+    }
+    // Generate sitemap.xml when a base URL is provided
+    if (baseUrl) {
+        const sitemapBase = baseUrl.replace(/\/$/, "");
+        const urls = documents
+            .map((doc) => {
+            const path = doc.slug === "" ? "/" : `/${doc.slug}/`;
+            return `  <url>\n    <loc>${sitemapBase}${path}</loc>\n  </url>`;
+        })
+            .join("\n");
+        const sitemapXml = `<?xml version="1.0" encoding="UTF-8"?>\n` +
+            `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n` +
+            `${urls}\n` +
+            `</urlset>\n`;
+        await writeFile(join(outputPath, "sitemap.xml"), sitemapXml, "utf-8");
+        totalSize += Buffer.byteLength(sitemapXml, "utf-8");
+    }
+    // Write HTML pages
+    for (const doc of documents) {
+        const pagePath = doc.slug === "" ? "/" : `/${doc.slug}/`;
+        const canonicalUrl = baseUrl ? `${baseUrl.replace(/\/$/, "")}${pagePath}` : undefined;
+        const html = renderLayout({
+            title: doc.title,
+            description: doc.description,
+            canonicalUrl,
+            content: doc.renderedHtml,
+            navigation: navigationTree,
+            currentSlug: doc.slug,
+            stylesheet: cssContent,
+            mode: "build",
+            mermaidBundleSrc,
+            mermaidInitScript,
+            navigationScript,
+            searchScript,
+        });
+        // Determine output file path
+        const htmlPath = doc.slug === ""
+            ? join(outputPath, "index.html")
+            : join(outputPath, doc.slug, "index.html");
+        // Create parent directories
+        await mkdir(dirname(htmlPath), { recursive: true });
+        // Write the HTML file
+        await writeFile(htmlPath, html, "utf-8");
+        totalSize += Buffer.byteLength(html, "utf-8");
+    }
+    return {
+        pageCount: documents.length,
+        totalSize,
+        outputPath,
+    };
+}
+/**
+ * Format bytes into a human-readable string.
+ */
+export function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+//# sourceMappingURL=builder.js.map

package/dist/build/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/build/builder.ts"],"names":[],"mappings":"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"}

package/dist/cli/build.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Build command handler.
+ * Orchestrates the full static build flow: validate, discover, render, write output.
+ */
+export interface BuildCommandOptions {
+    path: string;
+    output: string;
+    baseUrl?: string;
+}
+/**
+ * Execute the build command.
+ * Discovers files, renders them, builds navigation, writes static output.
+ */
+export declare function build(options: BuildCommandOptions): Promise<void>;

package/dist/cli/build.js

@@ -0,0 +1,116 @@
+/**
+ * Build command handler.
+ * Orchestrates the full static build flow: validate, discover, render, write output.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { discoverFiles } from "../core/discovery.js";
+import { generateSlug, generateSortKey, detectSlugCollisions, disambiguateSlugs, } from "../core/slug.js";
+import { getTitle } from "../core/title.js";
+import { extractFrontMatter } from "../render/pipeline.js";
+import { buildNavigationTree } from "../core/navigation.js";
+import { renderContent } from "../render/pipeline.js";
+import { buildSite, formatSize } from "../build/builder.js";
+import { getStylesheet } from "../theme/index.js";
+import { getMermaidBundleSrc, MERMAID_INIT_SCRIPT, NAVIGATION_SCRIPT, buildSearchScript, } from "../theme/scripts.js";
+/**
+ * Execute the build command.
+ * Discovers files, renders them, builds navigation, writes static output.
+ */
+export async function build(options) {
+    const sourcePath = resolve(options.path);
+    // Step 1: Discover files
+    const documents = await discoverFiles(sourcePath);
+    // Step 2: Read content, generate slugs, extract titles
+    await processDocuments(documents);
+    // Step 3: Check for slug collisions
+    checkSlugCollisions(documents);
+    // Step 4: Build navigation tree
+    const navigationTree = buildNavigationTree(documents);
+    // Step 5: Render all pages to HTML
+    await renderDocuments(documents);
+    // Step 6: Get theme assets
+    const stylesheet = getStylesheet();
+    // Step 7: Build static output
+    const result = await buildSite({
+        documents,
+        navigationTree,
+        stylesheet,
+        outputDir: options.output,
+        mermaidBundleSrc: getMermaidBundleSrc("build"),
+        mermaidInitScript: MERMAID_INIT_SCRIPT,
+        navigationScript: NAVIGATION_SCRIPT,
+        searchScript: buildSearchScript("assets/search.json"),
+        baseUrl: options.baseUrl,
+    });
+    // Print summary
+    console.log(`\nmdmirror build complete`);
+    console.log(`  Source: ${sourcePath}`);
+    console.log(`  Output: ${result.outputPath}`);
+    console.log(`  Pages:  ${result.pageCount}`);
+    console.log(`  Size:   ${formatSize(result.totalSize)}\n`);
+}
+/**
+ * Read file content, generate slugs, extract titles, and set sort keys.
+ * Skips files that can't be read (e.g. non-UTF-8 encoding) with a warning.
+ */
+async function processDocuments(documents) {
+    const failed = [];
+    await Promise.all(documents.map(async (doc) => {
+        try {
+            doc.content = await readFile(doc.absolutePath, "utf-8");
+            // Detect non-UTF-8 content (replacement character indicates encoding issues)
+            if (doc.content.includes("\uFFFD")) {
+                console.error(`Warning: Skipping ${doc.sourcePath} (appears to be non-UTF-8 encoded)`);
+                failed.push(doc);
+                return;
+            }
+            const { frontMatter } = extractFrontMatter(doc.content);
+            doc.slug = generateSlug(doc.sourcePath);
+            doc.title =
+                frontMatter.title ||
+                    getTitle(doc.content, doc.sourcePath);
+            doc.description = frontMatter.description || "";
+            const filename = doc.sourcePath.split(/[/\\]/).pop() || doc.sourcePath;
+            doc.sortKey = generateSortKey(filename.replace(/\.[^.]+$/, ""));
+        }
+        catch (error) {
+            console.error(`Warning: Skipping ${doc.sourcePath} (${error instanceof Error ? error.message : "read error"})`);
+            failed.push(doc);
+        }
+    }));
+    // Remove failed documents from the array
+    for (const doc of failed) {
+        const index = documents.indexOf(doc);
+        if (index !== -1)
+            documents.splice(index, 1);
+    }
+}
+/**
+ * Check for slug collisions, warn on stderr, and disambiguate with suffixes.
+ */
+function checkSlugCollisions(documents) {
+    const slugMap = new Map();
+    for (const doc of documents) {
+        const existing = slugMap.get(doc.slug) || [];
+        existing.push(doc.sourcePath);
+        slugMap.set(doc.slug, existing);
+    }
+    const collisions = detectSlugCollisions(slugMap);
+    for (const [slug, paths] of collisions) {
+        console.error(`Warning: Slug collision detected: "${slug}" maps to ${paths.join(" and ")} — disambiguating with suffixes`);
+    }
+    // Apply disambiguation suffixes to colliding slugs
+    if (collisions.size > 0) {
+        disambiguateSlugs(documents);
+    }
+}
+/**
+ * Render all document content to HTML.
+ */
+async function renderDocuments(documents) {
+    await Promise.all(documents.map(async (doc) => {
+        doc.renderedHtml = await renderContent(doc.content, doc.fileType);
+    }));
+}
+//# sourceMappingURL=build.js.map

package/dist/cli/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/cli/build.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for mdmirror.
+ * Handles manual subcommand routing since citty runs parent + subcommand.
+ */
+export {};

package/dist/cli/index.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for mdmirror.
+ * Handles manual subcommand routing since citty runs parent + subcommand.
+ */
+import { defineCommand, runMain } from "citty";
+import { serve } from "./serve.js";
+import { build } from "./build.js";
+// Detect if "build" subcommand is being invoked
+const isBuildCommand = process.argv[2] === "build";
+if (isBuildCommand) {
+    // Remove "build" from argv so citty parses the remaining args correctly
+    process.argv.splice(2, 1);
+    const buildCommand = defineCommand({
+        meta: {
+            name: "mdmirror build",
+            description: "Generate a self-contained static site for deployment",
+        },
+        args: {
+            path: {
+                type: "positional",
+                description: "Path to the source folder containing documentation",
+                required: true,
+            },
+            output: {
+                type: "string",
+                alias: "o",
+                description: "Output directory for the generated site",
+                default: "./dist",
+            },
+            "base-url": {
+                type: "string",
+                description: "Base URL for canonical links and sitemap (e.g. https://example.com)",
+                default: "",
+            },
+        },
+        async run({ args }) {
+            try {
+                await build({
+                    path: args.path,
+                    output: args.output,
+                    baseUrl: args["base-url"] || undefined,
+                });
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    console.error(`Error: ${error.message}`);
+                }
+                else {
+                    console.error("An unexpected error occurred");
+                }
+                process.exit(1);
+            }
+        },
+    });
+    runMain(buildCommand);
+}
+else {
+    const main = defineCommand({
+        meta: {
+            name: "mdmirror",
+            version: "1.0.0",
+            description: "Zero-config CLI tool that turns any folder of markdown files into a browsable documentation site",
+        },
+        args: {
+            path: {
+                type: "positional",
+                description: "Path to the source folder containing documentation",
+                required: true,
+            },
+            port: {
+                type: "string",
+                alias: "p",
+                description: "Port to serve on",
+                default: process.env["PORT"] || "3000",
+            },
+            host: {
+                type: "string",
+                description: "Bind address for the server",
+                default: "localhost",
+            },
+        },
+        async run({ args }) {
+            try {
+                await serve({
+                    path: args.path,
+                    port: parseInt(args.port, 10),
+                    host: args.host,
+                });
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    console.error(`Error: ${error.message}`);
+                }
+                else {
+                    console.error("An unexpected error occurred");
+                }
+                process.exit(1);
+            }
+        },
+    });
+    runMain(main);
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/serve.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Serve command handler.
+ * Orchestrates the full serve flow: validate, discover, render, serve, watch, live reload.
+ */
+export interface ServeOptions {
+    path: string;
+    port: number;
+    host: string;
+}
+/**
+ * Execute the serve command.
+ * Discovers files, renders them, builds navigation, starts the server,
+ * then watches for changes and triggers live reload.
+ */
+export declare function serve(options: ServeOptions): Promise<void>;

package/dist/cli/serve.js

@@ -0,0 +1,233 @@
+/**
+ * Serve command handler.
+ * Orchestrates the full serve flow: validate, discover, render, serve, watch, live reload.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve, relative } from "node:path";
+import { discoverFiles } from "../core/discovery.js";
+import { generateSlug, generateSortKey, detectSlugCollisions, disambiguateSlugs, } from "../core/slug.js";
+import { getTitle } from "../core/title.js";
+import { extractFrontMatter } from "../render/pipeline.js";
+import { buildNavigationTree } from "../core/navigation.js";
+import { renderContent } from "../render/pipeline.js";
+import { renderLayout } from "../theme/layout.js";
+import { startServer } from "../server/server.js";
+import { createReloadServer, LIVE_RELOAD_CLIENT_SCRIPT } from "../server/reload.js";
+import { startWatcher } from "../server/watcher.js";
+import { getStylesheet } from "../theme/index.js";
+import { getMermaidBundleSrc, MERMAID_INIT_SCRIPT, NAVIGATION_SCRIPT, buildSearchScript, } from "../theme/scripts.js";
+import { buildSearchIndex } from "../search/index.js";
+/**
+ * Execute the serve command.
+ * Discovers files, renders them, builds navigation, starts the server,
+ * then watches for changes and triggers live reload.
+ */
+export async function serve(options) {
+    const sourcePath = resolve(options.path);
+    // Step 1: Discover files
+    let documents = await discoverFiles(sourcePath);
+    // Step 2: Read content, generate slugs, extract titles
+    await processDocuments(documents);
+    // Step 3: Check for slug collisions
+    checkSlugCollisions(documents);
+    // Step 4: Build navigation tree
+    let navigationTree = buildNavigationTree(documents);
+    // Step 5: Render all pages to HTML
+    await renderDocuments(documents);
+    // Step 6: Generate full HTML pages
+    const stylesheet = getStylesheet();
+    let pages = generatePages(documents, navigationTree, stylesheet, "serve");
+    // Step 7: Start the server
+    const config = {
+        port: options.port,
+        host: options.host,
+        sourcePath,
+        liveReload: true,
+    };
+    const site = {
+        pages,
+        sourcePath,
+    };
+    const { server, updatePages } = await startServer(config, site);
+    // Step 8: Set up live reload WebSocket
+    const reloadServer = createReloadServer(server);
+    // Step 9: Start file watcher
+    let rebuilding = false;
+    const watcher = startWatcher({
+        sourcePath,
+        debounceMs: 300,
+        onChange: async (events) => {
+            if (rebuilding)
+                return;
+            rebuilding = true;
+            try {
+                const hasStructuralChange = events.some((e) => e.type === "add" || e.type === "unlink");
+                if (hasStructuralChange) {
+                    // Full rebuild: re-discover, re-process, re-render everything
+                    documents = await discoverFiles(sourcePath);
+                    await processDocuments(documents);
+                    checkSlugCollisions(documents);
+                    navigationTree = buildNavigationTree(documents);
+                    await renderDocuments(documents);
+                    pages = generatePages(documents, navigationTree, stylesheet, "serve");
+                    updatePages(pages);
+                    const addedFiles = events.filter((e) => e.type === "add").length;
+                    const removedFiles = events.filter((e) => e.type === "unlink").length;
+                    if (addedFiles > 0)
+                        console.log(`  + ${addedFiles} file(s) added`);
+                    if (removedFiles > 0)
+                        console.log(`  - ${removedFiles} file(s) removed`);
+                    console.log(`  Pages: ${navigationTree.totalPages}`);
+                }
+                else {
+                    // Incremental update: only re-render changed files
+                    for (const event of events) {
+                        if (event.type === "change") {
+                            const relativePath = relative(sourcePath, event.path);
+                            const doc = documents.find((d) => d.sourcePath === relativePath);
+                            if (doc) {
+                                doc.content = await readFile(doc.absolutePath, "utf-8");
+                                const { frontMatter: fm } = extractFrontMatter(doc.content);
+                                doc.title =
+                                    fm.title ||
+                                        getTitle(doc.content, doc.sourcePath);
+                                doc.description = fm.description || "";
+                                doc.renderedHtml = await renderContent(doc.content, doc.fileType);
+                                // Re-render the changed page (and update nav if title changed)
+                                navigationTree = buildNavigationTree(documents);
+                                pages = generatePages(documents, navigationTree, stylesheet, "serve");
+                                updatePages(pages);
+                                console.log(`  ~ ${relativePath} updated`);
+                            }
+                        }
+                    }
+                }
+                // Signal browsers to reload
+                reloadServer.reload();
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    console.error(`  Error during reload: ${error.message}`);
+                }
+            }
+            finally {
+                rebuilding = false;
+            }
+        },
+    });
+    // Print startup message
+    console.log(`\nmdmirror serving at http://${options.host}:${options.port}`);
+    console.log(`  Source: ${sourcePath}`);
+    console.log(`  Pages:  ${navigationTree.totalPages}`);
+    console.log(`  Live reload: enabled`);
+    console.log(`\n  Press Ctrl+C to stop\n`);
+    // Handle graceful shutdown
+    const shutdown = () => {
+        console.log("\nShutting down...");
+        reloadServer.close();
+        watcher.close();
+        server.close(() => process.exit(0));
+        // Force exit if server doesn't close promptly
+        setTimeout(() => process.exit(0), 2000).unref();
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+/**
+ * Read file content, generate slugs, extract titles, and set sort keys.
+ * Skips files that can't be read (e.g. non-UTF-8 encoding) with a warning.
+ */
+async function processDocuments(documents) {
+    const failed = [];
+    await Promise.all(documents.map(async (doc) => {
+        try {
+            // Read content
+            doc.content = await readFile(doc.absolutePath, "utf-8");
+            // Detect non-UTF-8 content (replacement character indicates encoding issues)
+            if (doc.content.includes("\uFFFD")) {
+                console.error(`Warning: Skipping ${doc.sourcePath} (appears to be non-UTF-8 encoded)`);
+                failed.push(doc);
+                return;
+            }
+            // Extract front matter (title/description overrides)
+            const { frontMatter } = extractFrontMatter(doc.content);
+            // Generate slug
+            doc.slug = generateSlug(doc.sourcePath);
+            // Extract title (front matter wins, then heading, then humanized filename)
+            doc.title =
+                frontMatter.title ||
+                    getTitle(doc.content, doc.sourcePath);
+            doc.description = frontMatter.description || "";
+            // Generate sort key from filename
+            const filename = doc.sourcePath.split(/[/\\]/).pop() || doc.sourcePath;
+            doc.sortKey = generateSortKey(filename.replace(/\.[^.]+$/, ""));
+        }
+        catch (error) {
+            console.error(`Warning: Skipping ${doc.sourcePath} (${error instanceof Error ? error.message : "read error"})`);
+            failed.push(doc);
+        }
+    }));
+    // Remove failed documents from the array
+    for (const doc of failed) {
+        const index = documents.indexOf(doc);
+        if (index !== -1)
+            documents.splice(index, 1);
+    }
+}
+/**
+ * Check for slug collisions, warn on stderr, and disambiguate with suffixes.
+ */
+function checkSlugCollisions(documents) {
+    const slugMap = new Map();
+    for (const doc of documents) {
+        const existing = slugMap.get(doc.slug) || [];
+        existing.push(doc.sourcePath);
+        slugMap.set(doc.slug, existing);
+    }
+    const collisions = detectSlugCollisions(slugMap);
+    for (const [slug, paths] of collisions) {
+        console.error(`Warning: Slug collision detected: "${slug}" maps to ${paths.join(" and ")} — disambiguating with suffixes`);
+    }
+    // Apply disambiguation suffixes to colliding slugs
+    if (collisions.size > 0) {
+        disambiguateSlugs(documents);
+    }
+}
+/**
+ * Render all document content to HTML.
+ */
+async function renderDocuments(documents) {
+    await Promise.all(documents.map(async (doc) => {
+        doc.renderedHtml = await renderContent(doc.content, doc.fileType);
+    }));
+}
+/**
+ * Generate full HTML pages for all documents.
+ * Returns a map of slug -> full HTML page.
+ */
+function generatePages(documents, navigationTree, stylesheet, mode) {
+    const pages = new Map();
+    const mermaidBundleSrc = getMermaidBundleSrc(mode);
+    for (const doc of documents) {
+        const html = renderLayout({
+            title: doc.title,
+            description: doc.description,
+            content: doc.renderedHtml,
+            navigation: navigationTree,
+            currentSlug: doc.slug,
+            stylesheet,
+            mode,
+            liveReloadScript: mode === "serve" ? LIVE_RELOAD_CLIENT_SCRIPT : undefined,
+            mermaidBundleSrc,
+            mermaidInitScript: MERMAID_INIT_SCRIPT,
+            navigationScript: NAVIGATION_SCRIPT,
+            searchScript: buildSearchScript("/assets/search.json"),
+        });
+        pages.set(doc.slug, html);
+    }
+    // Also expose the search index at /assets/search.json
+    const searchIndex = buildSearchIndex(documents);
+    pages.set("assets/search.json", JSON.stringify(searchIndex));
+    return pages;
+}
+//# sourceMappingURL=serve.js.map