create-zudo-doc 0.1.0

package/templates/base/src/types/docs-entry.ts

@@ -0,0 +1,39 @@
+/**
+ * Concrete entry type for docs collections.
+ *
+ * Mirrors the public surface that pages consume from `getCollection(...)`.
+ * Originally this was structurally identical to Astro's `CollectionEntry`
+ * but is defined locally now that the project runs on the zfb content
+ * engine — collection-name-specific generics are not exposed by zfb, so
+ * pages cast collection entries to this shape via `pages/_data.ts`.
+ */
+// Structural shape of zfb's optional rendered-content payload for a doc
+// entry (kept loose to stay engine-agnostic — pages do not rely on the
+// exact field set today).
+type RenderedContent = unknown;
+export interface DocsEntry {
+  id: string;
+  body?: string;
+  collection: string;
+  data: {
+    title: string;
+    description?: string;
+    category?: string;
+    sidebar_position?: number;
+    sidebar_label?: string;
+    tags?: string[];
+    search_exclude?: boolean;
+    pagination_next?: string | null;
+    pagination_prev?: string | null;
+    draft?: boolean;
+    unlisted?: boolean;
+    hide_sidebar?: boolean;
+    hide_toc?: boolean;
+    doc_history?: boolean;
+    standalone?: boolean;
+    slug?: string;
+    generated?: boolean;
+  };
+  rendered?: RenderedContent;
+  filePath?: string;
+}

package/templates/base/src/types/heading.ts

@@ -0,0 +1,5 @@
+export interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+}

package/templates/base/src/types/locale.ts

@@ -0,0 +1,10 @@
+/**
+ * Represents a locale switcher link.
+ * Used by both SidebarFooter (Preact) and language-switcher (Astro).
+ */
+export interface LocaleLink {
+  code: string;
+  label: string;
+  href: string;
+  active: boolean;
+}

package/templates/base/src/utils/base.ts

@@ -0,0 +1,139 @@
+import { settings } from "@/config/settings";
+import { defaultLocale, locales, getLocaleLabel, type Locale } from "@/config/i18n";
+import type { LocaleLink } from "@/types/locale";
+
+/** Normalized base path with no trailing slash (empty string when "/"). */
+export const normalizedBase = settings.base.replace(/\/+$/, "");
+
+/**
+ * Append a trailing slash to page URLs when `settings.trailingSlash` is true.
+ * Skips paths that already end with `/`, contain a file extension, or have a
+ * query string / fragment before the slash would be inserted.
+ */
+export function applyTrailingSlash(url: string): string {
+  if (!settings.trailingSlash) return url;
+  if (url.endsWith("/")) return url;
+  // Split off query string and fragment
+  const suffixIdx = url.search(/[?#]/);
+  const pathPart = suffixIdx >= 0 ? url.slice(0, suffixIdx) : url;
+  const suffix = suffixIdx >= 0 ? url.slice(suffixIdx) : "";
+  if (pathPart.endsWith("/")) return url;
+  // Check file extension on the last path segment only, requiring the extension
+  // to start with a letter to avoid false positives on version-like paths (e.g. /docs/v2.0)
+  const lastSegment = pathPart.split("/").pop() ?? "";
+  if (/\.[a-zA-Z]\w*$/.test(lastSegment)) return url;
+  return pathPart + "/" + suffix;
+}
+
+/** Prefix a path with the configured base directory. */
+export function withBase(path: string): string {
+  const raw =
+    normalizedBase === ""
+      ? path
+      : `${normalizedBase}${path.startsWith("/") ? path : `/${path}`}`;
+  return applyTrailingSlash(raw);
+}
+
+/** Strip the base prefix from a URL pathname. */
+export function stripBase(path: string): string {
+  if (normalizedBase === "") return path;
+  return path.startsWith(normalizedBase)
+    ? path.slice(normalizedBase.length) || "/"
+    : path;
+}
+
+/** Build a docs URL for the given slug and lang. */
+export function docsUrl(slug: string, lang: Locale = defaultLocale): string {
+  const path = lang === defaultLocale ? `/docs/${slug}` : `/${lang}/docs/${slug}`;
+  return withBase(path);
+}
+
+/** Check if a URL is external (starts with http:// or https://). */
+export function isExternal(href: string): boolean {
+  return href.startsWith("http://") || href.startsWith("https://");
+}
+
+/** Resolve a href: external URLs pass through, internal ones get the base prefix. */
+export function resolveHref(href: string): string {
+  return isExternal(href) ? href : withBase(href);
+}
+
+/**
+ * Build a localized, versioned nav href.
+ * Note: uses /{lang}/v/{version}/... ordering (for header/sidebar nav links).
+ * This differs from versionedDocsUrl() which uses /v/{version}/{lang}/... (for doc page links).
+ * Both orderings are handled by the routing layer.
+ */
+export function navHref(
+  path: string,
+  lang: Locale | undefined,
+  currentVersion: string | undefined,
+): string {
+  const isNonDefaultLocale = lang != null && lang !== defaultLocale;
+  const versionPrefix = currentVersion ? `/v/${currentVersion}` : "";
+  return withBase(
+    isNonDefaultLocale
+      ? `/${lang}${versionPrefix}${path}`
+      : `${versionPrefix}${path}`,
+  );
+}
+
+/** Build a locale-switched path from the current page path. */
+export function getPathForLocale(
+  path: string,
+  currentLang: Locale,
+  targetLang: Locale,
+): string {
+  let relativePath = stripBase(path);
+  if (currentLang !== defaultLocale) {
+    relativePath = relativePath.replace(new RegExp(`^/${currentLang}/`), "/");
+  }
+  if (targetLang !== defaultLocale) {
+    relativePath = `/${targetLang}${relativePath}`;
+  }
+  return withBase(relativePath);
+}
+
+/** Build locale links for locale switcher UI components. */
+export function buildLocaleLinks(currentPath: string, currentLang: Locale): LocaleLink[] {
+  let defaultLocalePath = stripBase(currentPath);
+  if (currentLang !== defaultLocale) {
+    defaultLocalePath = defaultLocalePath.replace(new RegExp(`^/${currentLang}/`), "/");
+  }
+  if (isDefaultLocaleOnlyPath(defaultLocalePath)) {
+    return [{
+      code: currentLang,
+      label: getLocaleLabel(currentLang),
+      href: getPathForLocale(currentPath, currentLang, currentLang),
+      active: true,
+    }];
+  }
+  return locales.map((code) => ({
+    code,
+    label: getLocaleLabel(code),
+    href: getPathForLocale(currentPath, currentLang, code),
+    active: code === currentLang,
+  }));
+}
+
+/**
+ * Returns true when the given default-locale-shaped path falls under one of
+ * the configured `defaultLocaleOnlyPrefixes`.  Callers that work with
+ * locale-prefixed paths (e.g. `/ja/docs/...`) are responsible for stripping
+ * the locale segment before calling this function.  The path is normalized to
+ * end with `/` before the comparison so the helper is robust to projects that
+ * disable `settings.trailingSlash` (where `docsUrl` returns slashless paths).
+ */
+export function isDefaultLocaleOnlyPath(path: string): boolean {
+  const stripped = stripBase(path);
+  const normalized = stripped.endsWith("/") ? stripped : `${stripped}/`;
+  return settings.defaultLocaleOnlyPrefixes.some((prefix) => normalized.startsWith(prefix));
+}
+
+/** Build a versioned docs URL for the given slug, version, and lang. */
+export function versionedDocsUrl(slug: string, versionSlug: string, lang: Locale = defaultLocale): string {
+  const path = lang === defaultLocale
+    ? `/v/${versionSlug}/docs/${slug}`
+    : `/v/${versionSlug}/${lang}/docs/${slug}`;
+  return withBase(path);
+}

package/templates/base/src/utils/content-files.ts

@@ -0,0 +1,106 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import matter from "gray-matter";
+import { settings } from "../config/settings";
+
+/** Strip markdown formatting to produce plain text */
+export function stripMarkdown(md: string): string {
+  return (
+    md
+      // Remove code blocks
+      .replace(/```[\s\S]*?```/g, "")
+      .replace(/`[^`]+`/g, "")
+      // Remove HTML tags
+      .replace(/<[^>]+>/g, "")
+      // Remove headings markers
+      .replace(/^#{1,6}\s+/gm, "")
+      // Remove emphasis/bold markers
+      .replace(/\*{1,3}([^*]+)\*{1,3}/g, "$1")
+      .replace(/_{1,3}([^_]+)_{1,3}/g, "$1")
+      // Remove images (must run before link removal)
+      .replace(/!\[[^\]]*\]\([^)]+\)/g, "")
+      // Remove links but keep text
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+      // Remove blockquote markers
+      .replace(/^>\s+/gm, "")
+      // Remove horizontal rules
+      .replace(/^[-*_]{3,}\s*$/gm, "")
+      // Remove list markers
+      .replace(/^[\s]*[-*+]\s+/gm, "")
+      .replace(/^[\s]*\d+\.\s+/gm, "")
+      // Remove import statements
+      .replace(/^import\s+.*$/gm, "")
+      // Remove export statements
+      .replace(/^export\s+.*$/gm, "")
+      // Collapse whitespace
+      .replace(/\n{3,}/g, "\n\n")
+      .trim()
+  );
+}
+
+/** Walk a directory and collect all .md/.mdx files */
+export function collectMdFiles(
+  dir: string,
+): Array<{ filePath: string; slug: string }> {
+  const results: Array<{ filePath: string; slug: string }> = [];
+
+  function walk(currentDir: string, baseDir: string): void {
+    let entries;
+    try {
+      entries = readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath, baseDir);
+      } else if (/\.mdx?$/.test(entry.name) && !entry.name.startsWith("_")) {
+        const rel = relative(baseDir, fullPath)
+          .replace(/\.mdx?$/, "")
+          .replace(/\/index$/, "");
+        results.push({ filePath: fullPath, slug: rel });
+      }
+    }
+  }
+
+  walk(dir, dir);
+  return results;
+}
+
+/** Compute a URL from a slug and locale. When absolute is true and siteUrl is configured, returns a full URL. */
+export function slugToUrl(slug: string, locale: string | null, absolute = false): string {
+  const base = settings.base.replace(/\/$/, "");
+  const path = locale ? `${base}/${locale}/docs/${slug}` : `${base}/docs/${slug}`;
+  if (absolute && settings.siteUrl) {
+    return `${settings.siteUrl.replace(/\/$/, "")}${path}`;
+  }
+  return path;
+}
+
+/** Frontmatter fields used across the project */
+export interface DocFrontmatter {
+  title?: string;
+  description?: string;
+  sidebar_position?: number;
+  category?: string;
+  draft?: boolean;
+  unlisted?: boolean;
+  search_exclude?: boolean;
+  [key: string]: unknown;
+}
+
+/** Parse a markdown file and return frontmatter + content */
+export function parseMarkdownFile(filePath: string): { data: DocFrontmatter; content: string } | null {
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    return matter(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** Check if a document should be excluded from indexing */
+export function isExcluded(data: DocFrontmatter): boolean {
+  return !!(data.search_exclude || data.draft || data.unlisted);
+}

package/templates/base/src/utils/dedent.ts

@@ -0,0 +1,24 @@
+/**
+ * Strip common leading whitespace from all lines of a template literal string.
+ * Similar to Python's textwrap.dedent().
+ */
+export function dedent(text: string): string {
+  const lines = text.split('\n');
+
+  // Find minimum indentation (ignoring empty/whitespace-only lines)
+  let minIndent = Infinity;
+  for (const line of lines) {
+    if (line.trim().length === 0) continue;
+    const indent = line.match(/^(\s*)/)?.[1].length ?? 0;
+    if (indent < minIndent) minIndent = indent;
+  }
+
+  if (minIndent === 0 || minIndent === Infinity) {
+    return text.trim();
+  }
+
+  return lines
+    .map((line) => (line.trim().length === 0 ? '' : line.slice(minIndent)))
+    .join('\n')
+    .trim();
+}

package/templates/base/src/utils/docs.ts

@@ -0,0 +1,335 @@
+import type { DocsEntry } from "@/types/docs-entry";
+import fs from "node:fs";
+import path from "node:path";
+import { toTitleCase, toRouteSlug } from "@/utils/slug";
+import { docsUrl, withBase } from "@/utils/base";
+import { defaultLocale, type Locale } from "@/config/i18n";
+
+/** Filter predicate: true when a doc should appear in navigation (sidebar, index, sitemap). */
+export function isNavVisible(doc: DocsEntry): boolean {
+  return !doc.data.unlisted && !doc.data.standalone;
+}
+
+export interface CategoryMeta {
+  label?: string;
+  position?: number;
+  description?: string;
+  sortOrder?: "asc" | "desc";
+  noPage?: boolean;
+}
+
+export interface NavNode {
+  slug: string;
+  label: string;
+  description?: string;
+  position: number;
+  href?: string;
+  hasPage: boolean;
+  children: NavNode[];
+  sortOrder?: "asc" | "desc";
+  collapsed?: boolean;
+}
+
+interface BuildNode {
+  segment: string;
+  fullPath: string;
+  doc?: DocsEntry;
+  children: Map<string, BuildNode>;
+}
+
+// Module-level caches — persist across all page renders during a single Astro build.
+const categoryMetaCache = new Map<string, Map<string, CategoryMeta>>();
+const navTreeCache = new Map<string, NavNode[]>();
+
+/** Build a cache key from docs array + locale + category meta.
+ *  Includes nav-affecting frontmatter so HMR picks up changes. */
+function navTreeCacheKey(
+  docs: DocsEntry[],
+  lang: Locale,
+  categoryMeta?: Map<string, CategoryMeta>,
+): string {
+  const metaKey = categoryMeta
+    ? JSON.stringify([...categoryMeta.entries()].sort(([a], [b]) => a.localeCompare(b)))
+    : "_";
+  return `${lang}:${metaKey}:${docs
+    .map((d) => {
+      const { sidebar_position, sidebar_label, title, description, unlisted, standalone, slug } =
+        d.data;
+      return JSON.stringify([
+        d.id,
+        sidebar_position,
+        sidebar_label,
+        title,
+        description,
+        unlisted,
+        standalone,
+        slug,
+      ]);
+    })
+    .sort()
+    .join(",")}`;
+}
+
+/**
+ * Build a recursive navigation tree from a flat Astro content collection.
+ * Mirrors the filesystem: directories become category nodes, files become leaves.
+ *
+ * Astro 5 glob() strips /index from IDs:
+ *   getting-started/index.mdx → ID "getting-started" (category index)
+ *   getting-started/intro.mdx → ID "getting-started/intro" (child page)
+ */
+export function buildNavTree(
+  docs: DocsEntry[],
+  lang: Locale = defaultLocale,
+  categoryMeta?: Map<string, CategoryMeta>,
+): NavNode[] {
+  const cacheKey = navTreeCacheKey(docs, lang, categoryMeta);
+  const cached = navTreeCache.get(cacheKey);
+  if (cached) return cached;
+
+  const root: BuildNode = {
+    segment: "",
+    fullPath: "",
+    children: new Map(),
+  };
+
+  for (const doc of docs) {
+    const slug = doc.data.slug ?? toRouteSlug(doc.id);
+    const parts = slug.split("/");
+
+    if (parts.length <= 1) {
+      // Category index: Astro 5 stripped /index → single segment like "guides"
+      const segment = doc.id;
+      if (!root.children.has(segment)) {
+        root.children.set(segment, {
+          segment,
+          fullPath: segment,
+          children: new Map(),
+        });
+      }
+      root.children.get(segment)!.doc = doc;
+    } else {
+      // Multi-segment: walk the tree creating intermediate nodes as needed
+      let current = root;
+      for (let i = 0; i < parts.length; i++) {
+        const segment = parts[i];
+        const fullPath = parts.slice(0, i + 1).join("/");
+        if (!current.children.has(segment)) {
+          current.children.set(segment, {
+            segment,
+            fullPath,
+            children: new Map(),
+          });
+        }
+        if (i === parts.length - 1) {
+          current.children.get(segment)!.doc = doc;
+        }
+        current = current.children.get(segment)!;
+      }
+    }
+  }
+
+  const result = toNavNodes(root, lang, categoryMeta);
+  navTreeCache.set(cacheKey, result);
+  return result;
+}
+
+function toNavNodes(
+  parent: BuildNode,
+  lang: Locale,
+  categoryMeta?: Map<string, CategoryMeta>,
+  parentSortOrder?: "asc" | "desc",
+): NavNode[] {
+  const nodes: NavNode[] = [];
+
+  for (const child of parent.children.values()) {
+    const doc = child.doc;
+    const meta = categoryMeta?.get(child.fullPath);
+    const sortOrder = meta?.sortOrder ?? "asc";
+    const children = toNavNodes(child, lang, categoryMeta, sortOrder);
+
+    nodes.push({
+      slug: child.fullPath,
+      label:
+        doc?.data.sidebar_label ?? doc?.data.title ?? meta?.label ?? toTitleCase(child.segment),
+      description: doc?.data.description ?? meta?.description,
+      position: doc?.data.sidebar_position ?? meta?.position ?? 999,
+      href: meta?.noPage
+        ? undefined
+        : doc || children.length > 0
+          ? docsUrl(child.fullPath, lang)
+          : undefined,
+      hasPage: !!doc,
+      children,
+      sortOrder,
+    });
+  }
+
+  // Use the PARENT's sortOrder to sort these sibling nodes
+  const order = parentSortOrder ?? "asc";
+  nodes.sort((a, b) => {
+    const posCompare = a.position - b.position;
+    if (posCompare !== 0) return order === "desc" ? -posCompare : posCompare;
+    const slugCompare = a.slug.localeCompare(b.slug);
+    return order === "desc" ? -slugCompare : slugCompare;
+  });
+
+  return nodes;
+}
+
+/**
+ * Group "satellite" nodes under their primary node based on slug prefixes.
+ * E.g. with prefix "claude", nodes "claude-md", "claude-commands" get moved
+ * under the "claude" node as children.
+ */
+export function groupSatelliteNodes(tree: NavNode[], prefixes: string[]): NavNode[] {
+  const result = [...tree];
+  for (const prefix of prefixes) {
+    const primaryIdx = result.findIndex((n) => n.slug === prefix);
+    if (primaryIdx < 0) continue;
+    const primary = result[primaryIdx];
+    const satelliteIdxs: number[] = [];
+    for (let i = 0; i < result.length; i++) {
+      if (i !== primaryIdx && result[i].slug.startsWith(`${prefix}-`)) {
+        satelliteIdxs.push(i);
+      }
+    }
+    if (satelliteIdxs.length === 0) continue;
+    const extraChildren: NavNode[] = [];
+    for (const idx of satelliteIdxs) {
+      extraChildren.push(result[idx]);
+    }
+    result[primaryIdx] = {
+      ...primary,
+      children: [...primary.children, ...extraChildren],
+    };
+    for (const idx of satelliteIdxs.reverse()) {
+      result.splice(idx, 1);
+    }
+  }
+  return result;
+}
+
+/** DFS flatten the tree for prev/next navigation. Only includes nodes with pages. */
+export function flattenTree(nodes: NavNode[]): NavNode[] {
+  const result: NavNode[] = [];
+  flattenInto(nodes, result);
+  return result;
+}
+
+function flattenInto(nodes: NavNode[], acc: NavNode[]): void {
+  for (const node of nodes) {
+    if (node.hasPage) {
+      acc.push(node);
+    }
+    flattenInto(node.children, acc);
+  }
+}
+
+/** Collect all category nodes that have children but no page (no index.mdx).
+ *  Nodes without href (e.g. noPage categories) are skipped — they are toggle-only. */
+export function collectAutoIndexNodes(nodes: NavNode[]): NavNode[] {
+  const result: NavNode[] = [];
+  for (const node of nodes) {
+    if (!node.hasPage && node.children.length > 0 && node.href) {
+      result.push(node);
+    }
+    result.push(...collectAutoIndexNodes(node.children));
+  }
+  return result;
+}
+
+/** Find a node by slug anywhere in the tree. */
+export function findNode(nodes: NavNode[], slug: string): NavNode | undefined {
+  for (const node of nodes) {
+    if (node.slug === slug) return node;
+    const found = findNode(node.children, slug);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+export interface BreadcrumbItem {
+  label: string;
+  href?: string;
+}
+
+/**
+ * Build breadcrumb trail by walking the nav tree.
+ */
+export function buildBreadcrumbs(
+  tree: NavNode[],
+  slug: string,
+  lang: Locale = defaultLocale,
+): BreadcrumbItem[] {
+  const parts = slug.split("/");
+  const homeHref = lang === defaultLocale ? withBase("/") : withBase(`/${lang}/`);
+  const crumbs: BreadcrumbItem[] = [{ label: "", href: homeHref }];
+  let nodes = tree;
+
+  for (let i = 0; i < parts.length; i++) {
+    const partialSlug = parts.slice(0, i + 1).join("/");
+    const node = nodes.find((n) => n.slug === partialSlug);
+    if (!node) break;
+
+    const isLast = i === parts.length - 1;
+    crumbs.push({
+      label: node.label,
+      href: isLast ? undefined : node.href,
+    });
+    nodes = node.children;
+  }
+
+  return crumbs;
+}
+
+/**
+ * Scan a content directory for _category_.json files and return a map
+ * of relative paths to category metadata.
+ * Results are memoized by contentDir.
+ */
+export function loadCategoryMeta(contentDir: string): Map<string, CategoryMeta> {
+  const cached = categoryMetaCache.get(contentDir);
+  if (cached) return cached;
+  const result = new Map<string, CategoryMeta>();
+  scanDir(contentDir, contentDir, result);
+  categoryMetaCache.set(contentDir, result);
+  return result;
+}
+
+function scanDir(baseDir: string, currentDir: string, result: Map<string, CategoryMeta>): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(currentDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const fullPath = path.join(currentDir, entry.name);
+      const categoryFile = path.join(fullPath, "_category_.json");
+      if (fs.existsSync(categoryFile)) {
+        try {
+          const raw = fs.readFileSync(categoryFile, "utf-8");
+          const parsed: unknown = JSON.parse(raw);
+          if (typeof parsed === "object" && parsed !== null) {
+            const obj = parsed as Record<string, unknown>;
+            const meta: CategoryMeta = {
+              label: typeof obj.label === "string" ? obj.label : undefined,
+              position: typeof obj.position === "number" ? obj.position : undefined,
+              description: typeof obj.description === "string" ? obj.description : undefined,
+              sortOrder: obj.sortOrder === "asc" || obj.sortOrder === "desc" ? obj.sortOrder : undefined,
+              noPage: obj.noPage === true ? true : undefined,
+            };
+            const relativePath = path.relative(baseDir, fullPath);
+            result.set(relativePath, meta);
+          }
+        } catch {
+          // skip invalid JSON
+        }
+      }
+      scanDir(baseDir, fullPath, result);
+    }
+  }
+}