@takazudo/zudo-doc 0.2.21 → 0.2.22

package/dist/preset.js

@@ -0,0 +1,169 @@
+import { z } from "zod";
+function zudoDocPreset({
+  settings,
+  buildDocsSchema,
+  directiveVocabulary
+}) {
+  const docsSchemaJson = z.toJSONSchema(buildDocsSchema());
+  return {
+    collections: buildCollections(settings, docsSchemaJson),
+    plugins: buildPlugins(settings),
+    markdown: { features: buildMarkdownFeatures(settings, directiveVocabulary) },
+    // Dual-theme syntect (zfb >= 0.1.0-next.45). Theme names are SYNTECT
+    // built-ins, NOT Shiki names. Tokens emit `--shiki-light`/`--shiki-dark`
+    // CSS custom properties resolved by the host CSS via `light-dark()`, so
+    // code follows the in-page light/dark switch with zero client JS.
+    codeHighlight: {
+      themeLight: "base16-ocean.light",
+      themeDark: "base16-ocean.dark"
+    },
+    resolveMarkdownLinks: buildResolveMarkdownLinks(settings),
+    // Strip `.md` / `.mdx` from in-page `<a href>` so author-written
+    // `[label](./other.mdx)` references resolve to the rendered route URL.
+    stripMdExt: true,
+    trailingSlash: settings.trailingSlash
+  };
+}
+function buildCollections(settings, docsSchemaJson) {
+  const collections = [];
+  collections.push({ name: "docs", path: settings.docsDir, schema: docsSchemaJson });
+  for (const [code, config] of Object.entries(settings.locales)) {
+    collections.push({ name: `docs-${code}`, path: config.dir, schema: docsSchemaJson });
+  }
+  if (settings.versions) {
+    for (const version of settings.versions) {
+      collections.push({
+        name: `docs-v-${version.slug}`,
+        path: version.docsDir,
+        schema: docsSchemaJson
+      });
+      if (version.locales) {
+        for (const [code, config] of Object.entries(version.locales)) {
+          collections.push({
+            name: `docs-v-${version.slug}-${code}`,
+            path: config.dir,
+            schema: docsSchemaJson
+          });
+        }
+      }
+    }
+  }
+  return collections;
+}
+function buildResolveMarkdownLinks(settings) {
+  return {
+    enabled: true,
+    dirs: [
+      { dir: settings.docsDir, routePrefix: "/docs/" },
+      ...Object.entries(settings.locales).map(([code, locale]) => ({
+        dir: locale.dir,
+        routePrefix: `/${code}/docs/`
+      })),
+      // Versioned collections: each version's EN dir + per-locale dirs.
+      ...settings.versions ? settings.versions.flatMap((version) => [
+        { dir: version.docsDir, routePrefix: `/v/${version.slug}/docs/` },
+        ...Object.entries(version.locales ?? {}).map(([code, locale]) => ({
+          dir: locale.dir,
+          routePrefix: `/v/${version.slug}/${code}/docs/`
+        }))
+      ]) : []
+    ],
+    onBrokenLinks: settings.onBrokenMarkdownLinks
+  };
+}
+function buildMarkdownFeatures(settings, directiveVocabulary) {
+  return {
+    // Former-Core directives (next.25 generic `directives` map). Keys are
+    // directive names, values are the JSX component names they resolve to
+    // (registered in the host's pages/_mdx-components.ts).
+    directives: { ...directiveVocabulary },
+    mermaid: settings.mermaid,
+    headingMarkerToc: true,
+    // Remaining opt-in features (#1804).
+    githubAlerts: true,
+    readingTime: true,
+    // owner/repo used to build `owner/repo#123`, `#123`, and SHA autolinks.
+    // Included only when settings.githubAutolinksRepo is set; omitted entirely
+    // for projects that don't configure a repo (restores old generated-project
+    // behaviour — zudo-doc#2321 Wave-0 correctness fix).
+    ...settings.githubAutolinksRepo ? { githubAutolinks: { repo: settings.githubAutolinksRepo } } : {},
+    codeEnrichment: {},
+    // codeTabs accepts the `true` shorthand; <CodeGroup> is registered host-side.
+    codeTabs: true,
+    // ruby — native `<ruby>` markup from `{base}^{ruby}` caret syntax.
+    ruby: true,
+    // tocExport — object-typed feature; `true` shorthand is rejected by the
+    // Rust loader, so pass `{}`.
+    tocExport: {},
+    imageDimensions: {},
+    // warn-only: failOnBroken=false never fails the build.
+    linkValidation: { failOnBroken: false },
+    // Heading-ID strategy is the single source of truth in settings, mirrored
+    // by the host TOC builder so anchors match the rendered IDs.
+    headingIds: { strategy: settings.headingIdStrategy }
+  };
+}
+function buildPlugins(settings) {
+  const localeArray = Object.entries(settings.locales).map(([code, locale]) => ({
+    code,
+    dir: locale.dir
+  }));
+  const localeRecord = Object.fromEntries(
+    Object.entries(settings.locales).map(([code, locale]) => [code, { dir: locale.dir }])
+  );
+  return [
+    ...settings.claudeResources ? [
+      {
+        name: "@takazudo/zudo-doc/plugins/claude-resources",
+        options: {
+          claudeDir: settings.claudeResources.claudeDir,
+          projectRoot: settings.claudeResources.projectRoot,
+          docsDir: settings.docsDir
+        }
+      }
+    ] : [],
+    ...settings.docHistory ? [
+      {
+        name: "@takazudo/zudo-doc/plugins/doc-history",
+        options: {
+          docsDir: settings.docsDir,
+          locales: localeRecord,
+          base: settings.base
+        }
+      }
+    ] : [],
+    {
+      name: "@takazudo/zudo-doc/plugins/search-index",
+      options: {
+        docsDir: settings.docsDir,
+        locales: localeRecord,
+        base: settings.base
+      }
+    },
+    ...settings.llmsTxt ? [
+      {
+        name: "@takazudo/zudo-doc/plugins/llms-txt",
+        options: {
+          siteName: settings.siteName,
+          siteDescription: settings.siteDescription,
+          base: settings.base,
+          siteUrl: settings.siteUrl,
+          defaultLocaleDir: settings.docsDir,
+          locales: localeArray
+        }
+      }
+    ] : [],
+    // copy-public stays a PROJECT-relative descriptor (NOT relocated in S3).
+    // Native zfb copy_public_dir is not yet validated for base="/", so the
+    // host plugin remains until that lands; deleted in place in a later epic.
+    {
+      name: "./plugins/copy-public-plugin.mjs",
+      options: {
+        publicDir: "public"
+      }
+    }
+  ];
+}
+export {
+  zudoDocPreset
+};

package/dist/render-markdown/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Lightweight markdown-to-HTML renderer for chat messages.
+ * Escapes HTML first, then applies markdown patterns — safe by construction.
+ */
+export declare function renderMarkdown(src: string): string;

package/dist/render-markdown/index.js

@@ -0,0 +1,115 @@
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+const ALLOWED_LINK_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
+function unescapeHtml(str) {
+  return str.replace(/&quot;/g, '"').replace(/&gt;/g, ">").replace(/&lt;/g, "<").replace(/&amp;/g, "&");
+}
+function safeHref(rawCapturedUrl) {
+  const decoded = unescapeHtml(rawCapturedUrl);
+  let parsed;
+  try {
+    parsed = new URL(decoded);
+  } catch {
+    return null;
+  }
+  if (!ALLOWED_LINK_PROTOCOLS.has(parsed.protocol)) return null;
+  return escapeHtml(encodeURI(decoded));
+}
+function renderInline(text) {
+  const codeSpans = [];
+  let processed = text.replace(/`([^`]+)`/g, (_match, code) => {
+    const idx = codeSpans.length;
+    codeSpans.push(`<code>${code}</code>`);
+    return `%%CODE_${idx}%%`;
+  });
+  const boldSpans = [];
+  processed = processed.replace(/\*\*(.+?)\*\*/g, (_match, inner) => {
+    const idx = boldSpans.length;
+    boldSpans.push(`<strong>${inner}</strong>`);
+    return `%%BOLD_${idx}%%`;
+  }).replace(/__(.+?)__/g, (_match, inner) => {
+    const idx = boldSpans.length;
+    boldSpans.push(`<strong>${inner}</strong>`);
+    return `%%BOLD_${idx}%%`;
+  });
+  processed = processed.replace(/\*(.+?)\*/g, "<em>$1</em>").replace(/(?<!\w)_(.+?)_(?!\w)/g, "<em>$1</em>").replace(/\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g, (_match, label, url) => {
+    const href = safeHref(url);
+    if (href === null) return `[${label}](${url})`;
+    return `<a href="${href}" target="_blank" rel="noopener noreferrer">${label}</a>`;
+  });
+  processed = processed.replace(/%%BOLD_(\d+)%%/g, (_match, idx) => boldSpans[parseInt(idx, 10)] ?? "");
+  return processed.replace(/%%CODE_(\d+)%%/g, (_match, idx) => codeSpans[parseInt(idx, 10)] ?? "");
+}
+function renderListBlock(block, marker, tag) {
+  const parts = [];
+  let proseLines = [];
+  let listItems = [];
+  const flushProse = () => {
+    if (proseLines.length > 0) {
+      parts.push(`<p>${proseLines.map(renderInline).join("<br>")}</p>`);
+      proseLines = [];
+    }
+  };
+  const flushList = () => {
+    if (listItems.length > 0) {
+      parts.push(`<${tag}>${listItems.join("")}</${tag}>`);
+      listItems = [];
+    }
+  };
+  for (const rawLine of block.split("\n")) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (marker.test(line)) {
+      flushProse();
+      listItems.push(`<li>${renderInline(line.replace(marker, ""))}</li>`);
+    } else {
+      flushList();
+      proseLines.push(line);
+    }
+  }
+  flushProse();
+  flushList();
+  return parts.join("");
+}
+function renderMarkdown(src) {
+  const escaped = escapeHtml(src);
+  const codeBlocks = [];
+  const withPlaceholders = escaped.replace(
+    /```(\w*)\n([\s\S]*?)```/g,
+    (_match, lang, code) => {
+      const idx = codeBlocks.length;
+      const langAttr = lang ? ` data-language="${lang}"` : "";
+      codeBlocks.push(`<pre${langAttr}><code>${code.trimEnd()}</code></pre>`);
+      return `
+%%CODEBLOCK_${idx}%%
+`;
+    }
+  );
+  const blocks = withPlaceholders.split(/\n{2,}/);
+  const rendered = blocks.map((block) => {
+    const trimmed = block.trim();
+    if (!trimmed) return "";
+    const cbMatch = trimmed.match(/^%%CODEBLOCK_(\d+)%%$/);
+    if (cbMatch) return codeBlocks[parseInt(cbMatch[1] ?? "0", 10)] ?? "";
+    if (/^[-*] /m.test(trimmed)) {
+      return renderListBlock(trimmed, /^[-*] /, "ul");
+    }
+    if (/^\d+\. /m.test(trimmed)) {
+      return renderListBlock(trimmed, /^\d+\. /, "ol");
+    }
+    const headingMatch = trimmed.match(/^(#{1,3}) (.+)$/);
+    if (headingMatch) {
+      const hashes = headingMatch[1] ?? "";
+      const headingText = headingMatch[2] ?? "";
+      const level = hashes.length;
+      return `<h${level + 3}>${renderInline(headingText)}</h${level + 3}>`;
+    }
+    const lines = trimmed.split("\n").map(renderInline).join("<br>");
+    return `<p>${lines}</p>`;
+  }).filter(Boolean).join("");
+  return rendered;
+}
+export {
+  renderMarkdown
+};

package/dist/robots.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Public entry for `@takazudo/zudo-doc/robots`.
+ *
+ * Renders the content of `robots.txt` from project settings.
+ * Extracted from `pages/robots.txt.tsx` so the same logic can be
+ * consumed by both the showcase page and every `create-zudo-doc`
+ * scaffold without copy-drift.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { renderRobots } from "@takazudo/zudo-doc/robots";
+ * import { settings } from "@/config/settings";
+ *
+ * export const contentType = "text/plain";
+ * export default () => renderRobots(settings);
+ * ```
+ */
+/** Minimal settings shape consumed by renderRobots. */
+export interface RobotsSettings {
+    /** When true, disallow all crawlers. */
+    noindex: boolean;
+    /** Base URL of the site, used to construct the Sitemap line. */
+    siteUrl?: string;
+    /** When true (and siteUrl is set), append a Sitemap: line. */
+    sitemap?: boolean;
+}
+/**
+ * Returns the plain-text content for `robots.txt` based on settings.
+ *
+ * - `noindex: true` → `Disallow: /` with no Sitemap line (advertising a
+ *   sitemap while disallowing all crawlers is contradictory).
+ * - Otherwise → `Allow: /` with an optional `Sitemap:` line when both
+ *   `siteUrl` and `sitemap` are truthy.
+ */
+export declare function renderRobots(settings: RobotsSettings): string;

package/dist/robots.js

@@ -0,0 +1,17 @@
+function renderRobots(settings) {
+  if (settings.noindex) {
+    return `User-agent: *
+Disallow: /
+`;
+  }
+  const siteUrlBase = (settings.siteUrl ?? "").replace(/\/$/, "");
+  const hasSitemapLine = siteUrlBase !== "" && settings.sitemap;
+  const sitemapLine = hasSitemapLine ? `Sitemap: ${siteUrlBase}/sitemap.xml
+` : "";
+  return `User-agent: *
+Allow: /
+${sitemapLine}`;
+}
+export {
+  renderRobots
+};

package/dist/route-enumerators/index.d.ts

@@ -0,0 +1,204 @@
+import type { NavSourceDocs } from "../nav-source-docs/index.js";
+import type { DocPageEntry, DocNavNode } from "../doc-page-props/index.js";
+export type { DocPageEntry, DocNavNode, NavSourceDocs };
+/**
+ * Minimal docs entry shape needed for tag enumeration (no Content/module_specifier).
+ */
+export interface DocsEntryForTags {
+    id: string;
+    data: {
+        slug?: string;
+        draft?: boolean;
+        unlisted?: boolean;
+        category_no_page?: boolean;
+        tags?: string[];
+        [key: string]: unknown;
+    };
+}
+/**
+ * Minimal version config shape needed for route enumeration.
+ */
+export interface VersionConfigForEnum {
+    slug: string;
+    docsDir?: string;
+    locales?: Record<string, {
+        dir?: string;
+    }>;
+}
+/**
+ * Minimal tag info shape — only the keys the tag URL enumerator needs.
+ */
+export interface TagInfoForEnum {
+    tag: string;
+    count: number;
+}
+/**
+ * Injected context for `createRouteEnumerators`.
+ *
+ * All host-specific singletons and utilities are passed in so the package
+ * factory never imports `@/` aliases.
+ */
+export interface RouteEnumeratorsContext {
+    /** Default locale code. Host passes `defaultLocale` from `@/config/i18n`. */
+    defaultLocale: string;
+    /**
+     * Getter for all non-default locale codes.
+     * Host passes `() => Object.keys(settings.locales)`.
+     * Called per invocation so mutations to settings.locales are picked up.
+     */
+    getLocaleKeys: () => readonly string[];
+    /**
+     * Getter for the configured versions list (or false/undefined).
+     * Host passes `() => settings.versions`.
+     * Called per invocation so mutations to settings.versions are picked up.
+     */
+    getVersions: () => VersionConfigForEnum[] | false | undefined;
+    /**
+     * Getter for whether tag pages are enabled.
+     * Host passes `() => settings.docTags`.
+     */
+    getDocTags: () => boolean | undefined;
+    /** `docsUrl(slug, lang)` from `@/utils/base` (resolved with settings). */
+    docsUrl: (slug: string, lang?: string) => string;
+    /** `versionedDocsUrl(slug, versionSlug, lang)` from `@/utils/base`. */
+    versionedDocsUrl: (slug: string, versionSlug: string, lang?: string) => string;
+    /** `withBase(path)` from `@/utils/base`. */
+    withBase: (path: string) => string;
+    /**
+     * Load docs from a named collection.
+     * Host passes `loadDocs` from `pages/_data.ts`.
+     */
+    loadDocs: (collectionName: string) => DocsEntryForTags[];
+    /**
+     * Returns true for paths that are only shown in the default locale.
+     * Host passes `isDefaultLocaleOnlyPath` from `@/utils/base`.
+     */
+    isDefaultLocaleOnlyPath: (path: string) => boolean;
+    /**
+     * Collect tags from a docs array.
+     * Host passes `collectTags` from `@/utils/tags`.
+     */
+    collectTags: (docs: DocsEntryForTags[], slugFn: (id: string, data: {
+        slug?: string;
+    }) => string) => Map<string, TagInfoForEnum>;
+    /**
+     * Convert a content entry slug to a canonical route slug.
+     * Host passes `toRouteSlug` from `@/utils/slug`.
+     */
+    toRouteSlug: (id: string) => string;
+    /**
+     * Build the nav tree for a locale.
+     * Host passes `buildNavTree` from `@/utils/docs`.
+     */
+    buildNavTree: (docs: DocPageEntry[], locale: string, categoryMeta: Map<string, unknown>) => DocNavNode[];
+    /**
+     * Collect auto-generated index nodes.
+     * Host passes `collectAutoIndexNodes` from `@/utils/docs`.
+     */
+    collectAutoIndexNodes: (tree: DocNavNode[]) => DocNavNode[];
+    /**
+     * Resolve the identity-stable nav source for an EN/locale context.
+     * Host passes `resolveNavSource` from `pages/lib/_nav-source-docs.ts`.
+     */
+    resolveNavSource: (lang: string, currentVersion: string | undefined, options?: {
+        applyDefaultLocaleOnlyFilter?: boolean;
+        keepUnlisted?: boolean;
+    }) => NavSourceDocs;
+    /**
+     * Resolve the identity-stable nav source for a versioned non-default-locale
+     * context.
+     * Host passes `resolveVersionedLocaleSource` from `pages/lib/_nav-source-docs.ts`.
+     */
+    resolveVersionedLocaleSource: (versionSlug: string, versionDocsDir: string | undefined, lang: string, localeDir: string | undefined, options?: {
+        applyDefaultLocaleOnlyFilter?: boolean;
+        keepUnlisted?: boolean;
+    }) => NavSourceDocs;
+    /**
+     * Merge locale docs with base-locale fallbacks.
+     * Host passes `mergeLocaleDocs` from `pages/lib/locale-merge.ts`.
+     */
+    mergeLocaleDocs: (options: {
+        baseDocs: DocsEntryForTags[];
+        localeDocs: DocsEntryForTags[];
+        applyDefaultLocaleOnlyFilter?: boolean;
+        keepUnlisted?: boolean;
+        isDefaultLocaleOnlyPath?: (path: string) => boolean;
+    }) => {
+        docs: DocsEntryForTags[];
+        localeSlugSet: ReadonlySet<string>;
+    };
+}
+export interface RouteEnumeratorsAPI {
+    /**
+     * Enumerate all doc page URLs for a locale.
+     *
+     * For the default locale: loads the "docs" collection directly.
+     * For non-default locales: locale-first merge with EN fallback, with
+     * default-locale-only paths excluded. A nav-tree pass adds auto-generated
+     * category index pages.
+     */
+    enumerateDocsRoutes: (locale: string) => string[];
+    /**
+     * Enumerate tag-index and per-tag URLs for a locale.
+     *
+     * Returns `/docs/tags/` and `/docs/tags/{tag}/` for each unique tag.
+     */
+    enumerateTagsRoutes: (locale: string) => string[];
+    /**
+     * Enumerate doc URLs for a single (version, locale) combination.
+     *
+     * For the default locale: loads the versioned EN collection.
+     * For non-default locales: locale-first merge over the version's EN base.
+     */
+    enumerateVersionedRoutes: (version: VersionConfigForEnum, locale: string) => string[];
+    /**
+     * Compose all route enumerators into a deduped Map<url, lastmod>.
+     *
+     * Covers site root, default-locale docs + tags, per-locale docs + tags,
+     * versioned EN docs, and versioned locale docs.
+     */
+    enumerateAllRoutes: () => Map<string, string>;
+}
+/**
+ * Create the route-enumeration functions bound to the host's injected context.
+ *
+ * @example
+ * ```ts
+ * // pages/lib/route-enumerators.ts (thin stub)
+ * import { createRouteEnumerators } from "@takazudo/zudo-doc/route-enumerators";
+ * import { settings } from "@/config/settings";
+ * import { defaultLocale } from "@/config/i18n";
+ * import { docsUrl, versionedDocsUrl, withBase, isDefaultLocaleOnlyPath } from "@/utils/base";
+ * import { buildNavTree, collectAutoIndexNodes } from "@/utils/docs";
+ * import { collectTags } from "@/utils/tags";
+ * import { toRouteSlug } from "@/utils/slug";
+ * import { loadDocs } from "../_data";
+ * import { resolveNavSource, resolveVersionedLocaleSource } from "./_nav-source-docs";
+ * import { mergeLocaleDocs } from "./locale-merge";
+ *
+ * export const {
+ *   enumerateDocsRoutes,
+ *   enumerateTagsRoutes,
+ *   enumerateVersionedRoutes,
+ *   enumerateAllRoutes,
+ * } = createRouteEnumerators({
+ *   defaultLocale,
+ *   getLocaleKeys: () => Object.keys(settings.locales),
+ *   getVersions: () => settings.versions,
+ *   getDocTags: () => settings.docTags,
+ *   docsUrl,
+ *   versionedDocsUrl,
+ *   withBase,
+ *   loadDocs,
+ *   isDefaultLocaleOnlyPath,
+ *   collectTags,
+ *   toRouteSlug,
+ *   buildNavTree,
+ *   collectAutoIndexNodes,
+ *   resolveNavSource,
+ *   resolveVersionedLocaleSource,
+ *   mergeLocaleDocs,
+ * });
+ * ```
+ */
+export declare function createRouteEnumerators(ctx: RouteEnumeratorsContext): RouteEnumeratorsAPI;