create-zudo-doc 0.1.0

package/templates/base/pages/lib/route-enumerators.ts

@@ -0,0 +1,302 @@
+// Pure URL-enumeration helpers shared by both page paths() functions and the
+// sitemap. Extracting these prevents the sitemap from drifting out of sync
+// with the actual routes the page modules produce.
+//
+// Each enumerator returns absolute paths (with settings.base prefix and
+// trailing slash applied) as expected by the sitemap and page modules.
+// `enumerateAllRoutes()` composes the others and returns a deduped
+// Map<url, lastmod> that the sitemap renderer wraps directly.
+//
+// Design principles:
+//   - Draft pages are always excluded (never built).
+//   - Unlisted pages ARE included — they have real HTML files and should
+//     appear in the sitemap even though they're hidden from nav.
+//   - toRouteSlug() is applied to all entry ids so category index pages
+//     (e.g. "getting-started/index" → "getting-started") get correct URLs.
+//   - Auto-generated category index pages (categories without index.mdx) are
+//     emitted by building the nav tree and calling collectAutoIndexNodes.
+
+import { loadDocs } from "../_data";
+import { mergeLocaleDocs } from "./locale-merge";
+import { settings } from "@/config/settings";
+import { defaultLocale } from "@/config/i18n";
+import type { VersionConfig } from "@/config/settings";
+import type { DocsEntry } from "@/types/docs-entry";
+import { docsUrl, versionedDocsUrl, withBase, isDefaultLocaleOnlyPath } from "@/utils/base";
+import { collectTags } from "@/utils/tags";
+import { toRouteSlug } from "@/utils/slug";
+import {
+  buildNavTree,
+  loadCategoryMeta,
+  collectAutoIndexNodes,
+  isNavVisible,
+} from "@/utils/docs";
+
+// ---------------------------------------------------------------------------
+// enumerateDocsRoutes
+// ---------------------------------------------------------------------------
+
+/**
+ * Enumerate all doc page URLs for a locale.
+ *
+ * For the default locale: loads the "docs" collection directly.
+ * For non-default locales: inlines a locale-first merge — locale docs take
+ * priority; base EN docs fill in slugs not covered by the locale collection,
+ * with default-locale-only paths excluded. A nav-tree pass then adds
+ * auto-generated category index pages.
+ *
+ * Applies toRouteSlug so "category/index" entries become "category/" URLs.
+ * Returns deduplicated URL strings with base prefix and trailing slash.
+ */
+export function enumerateDocsRoutes(locale: string): string[] {
+  const urls: string[] = [];
+
+  if (locale === defaultLocale) {
+    const allDocs = loadDocs("docs").filter((d) => !d.data.draft);
+    const categoryMeta = loadCategoryMeta(settings.docsDir);
+    const navDocs = allDocs.filter(isNavVisible);
+    const tree = buildNavTree(navDocs, locale, categoryMeta);
+
+    for (const doc of allDocs) {
+      urls.push(docsUrl(doc.data.slug ?? toRouteSlug(doc.id), locale as string));
+    }
+    for (const node of collectAutoIndexNodes(tree)) {
+      urls.push(docsUrl(node.slug, locale as string));
+    }
+  } else {
+    const localeDocs = loadDocs(`docs-${locale}`).filter((d) => !d.data.draft);
+    const baseDocs = loadDocs("docs").filter((d) => !d.data.draft);
+    const localeSlugSet = new Set(localeDocs.map((d) => d.data.slug ?? d.id));
+    const fallbackDocs = baseDocs.filter(
+      (d) => !localeSlugSet.has(d.data.slug ?? d.id) && !isDefaultLocaleOnlyPath(`/docs/${d.data.slug ?? d.id}`),
+    );
+    const allDocs = [...localeDocs, ...fallbackDocs] as DocsEntry[];
+
+    for (const doc of allDocs) {
+      urls.push(docsUrl(doc.data.slug ?? doc.id, locale as string));
+    }
+
+    const localeConfig = (
+      settings.locales as Record<string, { dir: string }>
+    )[locale];
+    const contentDir = localeConfig?.dir ?? settings.docsDir;
+    const categoryMeta = new Map([
+      ...loadCategoryMeta(settings.docsDir),
+      ...loadCategoryMeta(contentDir),
+    ]);
+
+    const navDocs = allDocs.filter(isNavVisible);
+    const tree = buildNavTree(navDocs, locale, categoryMeta);
+    for (const node of collectAutoIndexNodes(tree)) {
+      urls.push(docsUrl(node.slug, locale as string));
+    }
+  }
+
+  return [...new Set(urls)];
+}
+
+// ---------------------------------------------------------------------------
+// enumerateTagsRoutes
+// ---------------------------------------------------------------------------
+
+/**
+ * Enumerate tag-index and per-tag URLs for a locale.
+ *
+ * Uses the same tag map as the tag pages (unlisted + draft excluded) so the
+ * sitemap lists exactly the same tag pages that get built.
+ *
+ * Returns:
+ *   - /docs/tags/ (or /{locale}/docs/tags/)
+ *   - /docs/tags/{tag}/ (or /{locale}/docs/tags/{tag}/) for each unique tag
+ */
+export function enumerateTagsRoutes(locale: string): string[] {
+  if (!settings.docTags) return [];
+
+  const urls: string[] = [];
+
+  const tagsBase =
+    locale === defaultLocale ? "/docs/tags" : `/${locale}/docs/tags`;
+  urls.push(withBase(tagsBase));
+
+  // Collect tags from the same merged doc set the tag pages use.
+  // mergeLocaleDocs (locale-merge.ts) filters unlisted + draft — mirrors
+  // the tag [tag].tsx pages which do the same filter.
+  let docs: DocsEntry[];
+  if (locale === defaultLocale) {
+    docs = loadDocs("docs").filter((d) => !d.data.unlisted && !d.data.draft);
+  } else {
+    docs = mergeLocaleDocs(locale);
+  }
+
+  const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+
+  for (const tag of tagMap.keys()) {
+    const tagPath =
+      locale === defaultLocale
+        ? `/docs/tags/${tag}`
+        : `/${locale}/docs/tags/${tag}`;
+    urls.push(withBase(tagPath));
+  }
+
+  return urls;
+}
+
+// ---------------------------------------------------------------------------
+// enumerateVersionedRoutes
+// ---------------------------------------------------------------------------
+
+/**
+ * Enumerate doc URLs for a single (version, locale) combination.
+ *
+ * For the default locale: loads `docs-v-${version.slug}`.
+ * For non-default locales: locale-first merge — locale-specific collection
+ * takes priority; base EN collection fills in pages not yet translated.
+ * If the locale collection doesn't exist for this version, all pages fall
+ * back to the EN base (matching the page module's behaviour).
+ *
+ * Returns versioned URLs like /v/{version}/docs/{slug}/ or
+ * /v/{version}/{locale}/docs/{slug}/.
+ */
+export function enumerateVersionedRoutes(
+  version: VersionConfig,
+  locale: string,
+): string[] {
+  const urls: string[] = [];
+
+  if (locale === defaultLocale) {
+    const collectionName = `docs-v-${version.slug}`;
+    const allDocs = loadDocs(collectionName).filter((d) => !d.data.draft);
+    const categoryMeta = loadCategoryMeta(version.docsDir);
+    const navDocs = allDocs.filter(isNavVisible);
+    const tree = buildNavTree(navDocs, "en", categoryMeta);
+
+    for (const doc of allDocs) {
+      const slug = doc.data.slug ?? toRouteSlug(doc.id);
+      urls.push(versionedDocsUrl(slug, version.slug));
+    }
+    for (const node of collectAutoIndexNodes(tree)) {
+      urls.push(versionedDocsUrl(node.slug, version.slug));
+    }
+  } else {
+    const baseCollectionName = `docs-v-${version.slug}`;
+    const localeDir = (
+      version.locales as Record<string, { dir: string }> | undefined
+    )?.[locale]?.dir;
+    const localeCollectionName = localeDir
+      ? `docs-v-${version.slug}-${locale}`
+      : null;
+
+    const baseDocs = loadDocs(baseCollectionName).filter((d) => !d.data.draft);
+    const localeDocs = localeCollectionName
+      ? loadDocs(localeCollectionName).filter((d) => !d.data.draft)
+      : [];
+
+    const localeSlugSet = new Set(localeDocs.map((d) => d.data.slug ?? d.id));
+    const fallbackDocs = baseDocs.filter(
+      (d) => !localeSlugSet.has(d.data.slug ?? d.id) && !isDefaultLocaleOnlyPath(`/docs/${d.data.slug ?? d.id}`),
+    );
+    const allDocs = [...localeDocs, ...fallbackDocs] as DocsEntry[];
+
+    const baseCategoryMeta = loadCategoryMeta(version.docsDir);
+    const localeCategoryMeta = localeDir
+      ? loadCategoryMeta(localeDir)
+      : new Map();
+    const categoryMeta = new Map([...baseCategoryMeta, ...localeCategoryMeta]);
+
+    const navDocs = allDocs.filter(isNavVisible);
+    const tree = buildNavTree(navDocs, locale, categoryMeta);
+
+    for (const doc of allDocs) {
+      const slug = doc.data.slug ?? toRouteSlug(doc.id);
+      urls.push(versionedDocsUrl(slug, version.slug, locale as string));
+    }
+    for (const node of collectAutoIndexNodes(tree)) {
+      urls.push(versionedDocsUrl(node.slug, version.slug, locale as string));
+    }
+  }
+
+  return [...new Set(urls)];
+}
+
+// ---------------------------------------------------------------------------
+// enumerateAllRoutes
+// ---------------------------------------------------------------------------
+
+/**
+ * Compose all route enumerators into a deduped Map<url, lastmod>.
+ *
+ * Covers:
+ *   - Site root
+ *   - Default-locale docs + tags
+ *   - Per-locale homepages, docs, and tags
+ *   - Versioned EN docs (for each version in settings.versions)
+ *   - Versioned locale docs (for each locale in settings.locales)
+ *
+ * The map keys are absolute paths (with settings.base prefix + trailing
+ * slash). The sitemap renderer prefixes each with settings.siteUrl.
+ */
+export function enumerateAllRoutes(): Map<string, string> {
+  const today = new Date().toISOString().split("T")[0];
+  const routes = new Map<string, string>();
+
+  function add(url: string): void {
+    if (!routes.has(url)) {
+      routes.set(url, today);
+    }
+  }
+
+  // Site root
+  add(withBase("/"));
+
+  // Default locale docs
+  for (const url of enumerateDocsRoutes(defaultLocale)) {
+    add(url);
+  }
+
+  // Default locale tags
+  for (const url of enumerateTagsRoutes(defaultLocale)) {
+    add(url);
+  }
+
+  // Non-default locales
+  for (const locale of Object.keys(settings.locales)) {
+    add(withBase(`/${locale}`));
+
+    for (const url of enumerateDocsRoutes(locale)) {
+      add(url);
+    }
+
+    for (const url of enumerateTagsRoutes(locale)) {
+      add(url);
+    }
+  }
+
+  // Versions listing pages — /docs/versions/ and /{locale}/docs/versions/.
+  // These static utility pages are built by pages/docs/versions.tsx and
+  // pages/[locale]/docs/versions.tsx whenever versioning is configured.
+  // They are not part of any content collection so they are added explicitly.
+  if (settings.versions) {
+    add(withBase("/docs/versions"));
+    for (const locale of Object.keys(settings.locales)) {
+      add(withBase(`/${locale}/docs/versions`));
+    }
+  }
+
+  // Versioned docs
+  if (settings.versions) {
+    for (const version of settings.versions as VersionConfig[]) {
+      for (const url of enumerateVersionedRoutes(version, defaultLocale)) {
+        add(url);
+      }
+      // Non-default locales always have versioned pages (they fall back to EN
+      // when a locale-specific collection is not configured).
+      for (const locale of Object.keys(settings.locales)) {
+        for (const url of enumerateVersionedRoutes(version, locale)) {
+          add(url);
+        }
+      }
+    }
+  }
+
+  return routes;
+}

package/templates/base/pages/sitemap.xml.tsx

@@ -0,0 +1,51 @@
+// Port of `src/integrations/sitemap.ts` onto zfb's pages-style filename
+// convention.
+//
+// Filename → output extension mapping (zfb convention): the
+// second-to-last `.`-separated segment of the stem becomes the output
+// extension, so `sitemap.xml.tsx` builds `dist/sitemap.xml`. The
+// explicit `contentType` export pins the dev-server `Content-Type`
+// header to `application/xml` regardless of the filename hint.
+//
+// URL enumeration is delegated to `pages/lib/route-enumerators.ts` so
+// the sitemap cannot drift from the actual routes the page modules build.
+// Previously the sitemap walked raw collection slugs directly and missed:
+//   (a) tag pages           (b) JA fallback URLs
+//   (c) versioned JA routes (d) wrong URL pattern for versioned-locale pages
+//   (e) emitted /index/ suffix on category pages (closes #690)
+
+import { settings } from "@/config/settings";
+import { enumerateAllRoutes } from "./lib/route-enumerators";
+
+export const frontmatter = { title: "Sitemap" };
+export const contentType = "application/xml";
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+export default function Sitemap(): string {
+  const routeMap = enumerateAllRoutes();
+  const siteUrlBase = (settings.siteUrl ?? "").replace(/\/$/, "");
+
+  const urlEntries = [...routeMap.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(
+      ([url, lastmod]) => `  <url>
+    <loc>${escapeXml(siteUrlBase + url)}</loc>
+    <lastmod>${lastmod}</lastmod>
+  </url>`,
+    )
+    .join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urlEntries}
+</urlset>
+`;
+}

package/templates/base/plugins/connect-adapter.mjs

@@ -0,0 +1,144 @@
+// Adapter from Connect-style middleware (`(req, res, next) => void`) to
+// the request-response shape zfb's `devMiddleware` lifecycle hook
+// expects (`(req: ZfbDevMiddlewareRequest) => Promise<ZfbDevMiddlewareResponse | undefined>`).
+//
+// zfb's plugin host runs in a separate Node subprocess and only sees a
+// JSON envelope of the request — `{ method, url, headers, body? }` —
+// not real Node IPC. The adapter mocks just enough of `IncomingMessage`
+// and `ServerResponse` for the v2 integration middlewares (which were
+// written against Node's `http` types) to think they are talking to a
+// regular HTTP server, then captures the response status / headers /
+// body and returns them in the shape the host expects.
+//
+// The adapter is shared by every plugin module under this directory so
+// any future Connect-style middleware can be wired into zfb's
+// devMiddleware hook without rewriting it. Lives at the host repo —
+// the v2 integration package keeps its Connect-style API surface so
+// non-zfb embedders (Astro, plain Vite, a unit test) continue to work.
+
+import { Buffer } from "node:buffer";
+
+/**
+ * Convert a Connect-style middleware to a zfb devMiddleware handler.
+ * The returned async function takes a `ZfbDevMiddlewareRequest` and
+ * returns either `undefined` (passthrough — zfb falls through to its
+ * built-in routes) or a `ZfbDevMiddlewareResponse` envelope.
+ *
+ * Behaviour:
+ *
+ *   - `next()` from the middleware → resolves with `undefined`
+ *     (passthrough).
+ *   - `res.end(body)` → resolves with `{ status, headers, body }`.
+ *     `status` defaults to 200 if the middleware didn't set one,
+ *     mirroring Node's `ServerResponse` default.
+ *   - `next(err)` or a thrown error → rejects so the host surfaces a
+ *     500 with the error message the same way it does for any other
+ *     plugin throw.
+ *   - Binary bodies (Buffer / Uint8Array) → encoded as base64 and
+ *     flagged `bodyEncoding: "base64"` so the JSON envelope round-trip
+ *     stays loss-less.
+ */
+export function connectToZfbHandler(middleware) {
+  return (zfbReq) => {
+    return new Promise((resolveResponse, rejectResponse) => {
+      // Build a minimal `IncomingMessage` shim. Only the fields the v2
+      // integration middlewares actually read are populated — `method`,
+      // `url`, and `headers`. Body parsing is not used by any of the
+      // three middlewares (they're all GET routes), so we leave the
+      // stream surface unimplemented.
+      const req = {
+        method: zfbReq.method,
+        url: zfbReq.url,
+        headers: zfbReq.headers ?? {},
+      };
+
+      // Build a `ServerResponse` shim that captures status, headers,
+      // and body. We expose the API surface the v2 middlewares touch
+      // today (`statusCode`, `setHeader`, `getHeader`, `end`) — extend
+      // here if a future middleware needs more.
+      let statusCode = 200;
+      const headers = {};
+      let settled = false;
+
+      const finish = (body) => {
+        if (settled) return;
+        settled = true;
+        // Lower-case header names so the host's response shape matches
+        // axum's expectation (`Record<string, string>` of arbitrary
+        // case). Last-wins on collision; with `setHeader` callers this
+        // shouldn't happen.
+        const normalisedHeaders = {};
+        for (const [k, v] of Object.entries(headers)) {
+          normalisedHeaders[k.toLowerCase()] = String(v);
+        }
+
+        if (Buffer.isBuffer(body) || body instanceof Uint8Array) {
+          resolveResponse({
+            status: statusCode,
+            headers: normalisedHeaders,
+            body: Buffer.from(body).toString("base64"),
+            bodyEncoding: "base64",
+          });
+          return;
+        }
+        resolveResponse({
+          status: statusCode,
+          headers: normalisedHeaders,
+          body: body == null ? "" : String(body),
+          bodyEncoding: "utf8",
+        });
+      };
+
+      const res = {
+        get statusCode() {
+          return statusCode;
+        },
+        set statusCode(v) {
+          statusCode = v;
+        },
+        setHeader(name, value) {
+          headers[name] = value;
+        },
+        getHeader(name) {
+          // Header lookup is case-insensitive in Node's real
+          // ServerResponse — mirror that so middlewares that probe an
+          // existing header before overwriting it (`if
+          // (!res.getHeader("Content-Type"))`) keep working.
+          const lower = name.toLowerCase();
+          for (const [k, v] of Object.entries(headers)) {
+            if (k.toLowerCase() === lower) return v;
+          }
+          return undefined;
+        },
+        get headersSent() {
+          return settled;
+        },
+        end(body) {
+          finish(body);
+        },
+      };
+
+      const next = (err) => {
+        if (settled) return;
+        if (err) {
+          settled = true;
+          rejectResponse(err instanceof Error ? err : new Error(String(err)));
+          return;
+        }
+        // Connect's `next()` with no error means "I did not handle
+        // this request". Resolve with `undefined` so zfb's host
+        // surfaces a passthrough.
+        settled = true;
+        resolveResponse(undefined);
+      };
+
+      try {
+        middleware(req, res, next);
+      } catch (err) {
+        if (settled) return;
+        settled = true;
+        rejectResponse(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  };
+}

package/templates/base/plugins/copy-public-plugin.mjs

@@ -0,0 +1,50 @@
+// zfb plugin module: copy-public.
+//
+// Workaround for upstream zfb gap — `zfb build` does not copy `public/`
+// contents to `outDir`. See: zudolab/zudo-doc#1394;
+// upstream issue: https://github.com/Takazudo/zudo-front-builder/issues/158
+//
+// postBuild — recursively copies `<projectRoot>/public/` directly into
+//             `<outDir>/` (FLAT, matching zfb's own dist/ convention —
+//             zfb emits dist/index.html, dist/assets/..., NOT
+//             dist/<base>/index.html). Under the Workers static assets
+//             deploy (base="/"), `dist/` is served at root directly by
+//             `wrangler deploy` — no deploy-pipeline relocation step is
+//             needed. The `base` option is intentionally unused here.
+//
+//             Example: `public/img/logo.svg` becomes `dist/img/logo.svg`,
+//             served at `/img/logo.svg` by the Workers static asset layer.
+//
+// Missing or empty `public/` is treated as a no-op (no error).
+//
+// `options` carries `{ publicDir }` from the matching entry in
+// `zfb.config.ts`. The `base` option is intentionally unused — see
+// rationale above.
+
+import { cp } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export default {
+  name: "copy-public",
+
+  async postBuild(ctx) {
+    const { publicDir: publicDirOption } = ctx.options;
+    const publicDir = resolve(ctx.projectRoot, publicDirOption ?? "public");
+    const dest = ctx.outDir;
+
+    ctx.logger.info(`copying ${publicDir} → ${dest}`);
+
+    await cp(publicDir, dest, {
+      recursive: true,
+      force: true,
+      errorOnExist: false,
+    }).catch((err) => {
+      if (err.code === "ENOENT") {
+        // publicDir does not exist or is empty — treat as no-op.
+        ctx.logger.info("public/ not found — skipping copy");
+        return;
+      }
+      throw err;
+    });
+  },
+};

package/templates/base/plugins/search-index-plugin.mjs

@@ -0,0 +1,54 @@
+// zfb plugin module: search-index.
+//
+// Wires two lifecycle hooks for the search-index integration:
+//
+//   postBuild — invokes `emitSearchIndex` to write `dist/search-index.json`.
+//               There is no settings gate — the index is always emitted,
+//               matching the legacy Astro behaviour.
+//
+//   devMiddleware — rebuilds the in-memory search index from disk on every
+//               request so authoring edits surface without a dev-server
+//               restart. Registered at `/search-index.json`.
+//
+// `options` carries `{ docsDir, locales, base }` from the matching entry
+// in `zfb.config.ts`.
+//
+// Inline functions are not supported by zfb's plugin runtime; see the
+// sibling `doc-history-plugin.mjs` for the rationale.
+
+import { emitSearchIndex, createSearchIndexDevMiddleware } from "@takazudo/zudo-doc/integrations/search-index";
+import { connectToZfbHandler } from "./connect-adapter.mjs";
+
+export default {
+  name: "search-index",
+
+  postBuild(ctx) {
+    const { docsDir, locales, base } = ctx.options;
+    emitSearchIndex({
+      outDir: ctx.outDir,
+      docsDir,
+      locales,
+      base,
+      logger: ctx.logger,
+    });
+  },
+
+  devMiddleware(ctx) {
+    const middleware = createSearchIndexDevMiddleware(ctx.options);
+    // zfb's `register(path, handler)` matches against the FULL request
+    // URL (no base-stripping). For a non-root base (e.g. "/my-docs/"),
+    // requests arrive as `/my-docs/search-index.json`, so we register
+    // the full base-prefixed route. For base="/", the prefix is empty
+    // and the route is `/search-index.json` as expected. The v2
+    // middleware itself is base-tolerant (matches via
+    // `endsWith("/search-index.json")`), so it does not need a
+    // separate base-stripping pass.
+    const basePrefix = stripTrailingSlash(ctx.options.base ?? "");
+    ctx.register(`${basePrefix}/search-index.json`, connectToZfbHandler(middleware));
+  },
+};
+
+function stripTrailingSlash(s) {
+  if (typeof s !== "string" || s.length === 0) return "";
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}