create-zudo-doc 0.1.0

package/templates/base/src/config/tag-vocabulary-types.ts

@@ -0,0 +1,39 @@
+/**
+ * Tag governance enforcement level.
+ *
+ * - `"off"`   — no vocabulary-aware enforcement. The `tags` schema stays a
+ *               free-form `string[]`. Identical to pre-vocabulary behaviour.
+ * - `"warn"`  — `tags` schema stays free-form so builds pass, but the tag
+ *               audit script (see Sub 2) reports unknown tags as warnings and
+ *               exits non-zero under `--ci`.
+ * - `"strict"` — `tags` schema is tightened to `z.enum([...allowedIds])`, so
+ *                unknown tags fail `pnpm check` / `pnpm build`.
+ *
+ * Orthogonal to `tagVocabulary` (the on/off switch for consulting the
+ * vocabulary file at runtime). See `settings-types.ts` for details.
+ */
+export type TagGovernanceMode = "off" | "warn" | "strict";
+
+/**
+ * A single entry in the tag vocabulary.
+ *
+ * - `id`         — canonical tag id. What content files should ideally use.
+ * - `label`      — optional human-readable label (falls back to `id`).
+ * - `description`— optional short description for tooling / tag index pages.
+ * - `group`      — optional grouping key used by the grouped tag footer
+ *                  (e.g. `"type"`, `"level"`, `"topic"`).
+ * - `aliases`    — alternate strings that content files may use. Alias
+ *                  resolution rewrites these to `id` before aggregation.
+ * - `deprecated` — `true` marks the tag as deprecated with no redirect: the
+ *                  canonical id is dropped from aggregation. Pass
+ *                  `{ redirect: "<other-id>" }` to rewrite this tag to another
+ *                  canonical id when it appears in content.
+ */
+export interface TagVocabularyEntry {
+  id: string;
+  label?: string;
+  description?: string;
+  group?: string;
+  aliases?: readonly string[];
+  deprecated?: boolean | { redirect?: string };
+}

package/templates/base/src/config/tag-vocabulary.ts

@@ -0,0 +1,20 @@
+import type { TagVocabularyEntry } from "./tag-vocabulary-types";
+
+/**
+ * Canonical tag vocabulary for this documentation base.
+ *
+ * Populate this array with the tags you use in `src/content/docs/**`.
+ * Then enable `tagGovernance: "warn"` (or `"strict"`) and
+ * `tagVocabulary: true` in `settings.ts` to activate alias resolution,
+ * deprecation filtering, and grouped tag rendering.
+ *
+ * Example entry:
+ *
+ *     {
+ *       id: "type:guide",
+ *       label: "Guide",
+ *       group: "type",
+ *       aliases: ["guide", "guides"],
+ *     }
+ */
+export const tagVocabulary: readonly TagVocabularyEntry[] = [];

package/templates/base/src/hooks/use-active-heading.ts

@@ -0,0 +1,133 @@
+import { useCallback, useEffect, useRef, useState } from "preact/compat";
+import type { Heading } from "@/types/heading";
+
+const SCROLL_MARGIN_TOP = 80;
+const DEBOUNCE_MS = 200;
+
+function getActiveHeadingId(
+  headingIds: string[],
+  elementMap: Map<string, HTMLElement>,
+): string | null {
+  if (headingIds.length === 0) return null;
+
+  const viewportHeight = window.innerHeight;
+
+  let firstVisibleIndex = -1;
+  for (let i = 0; i < headingIds.length; i++) {
+    const el = elementMap.get(headingIds[i]);
+    if (!el) continue;
+    const { top } = el.getBoundingClientRect();
+    if (top >= SCROLL_MARGIN_TOP) {
+      firstVisibleIndex = i;
+      break;
+    }
+  }
+
+  if (firstVisibleIndex === -1) {
+    return headingIds[headingIds.length - 1];
+  }
+
+  if (firstVisibleIndex === 0) {
+    const el = elementMap.get(headingIds[0]);
+    if (el) {
+      const { top } = el.getBoundingClientRect();
+      if (top < viewportHeight / 2) {
+        return headingIds[0];
+      }
+    }
+    return null;
+  }
+
+  const el = elementMap.get(headingIds[firstVisibleIndex]);
+  if (el) {
+    const { top } = el.getBoundingClientRect();
+    if (top < viewportHeight / 2) {
+      return headingIds[firstVisibleIndex];
+    }
+  }
+
+  return headingIds[firstVisibleIndex - 1];
+}
+
+interface UseActiveHeadingResult {
+  activeId: string | null;
+  activate: (id: string) => void;
+}
+
+export function useActiveHeading(
+  headings: Heading[],
+): UseActiveHeadingResult {
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const headingIdsRef = useRef<string[]>([]);
+  const elementMapRef = useRef<Map<string, HTMLElement>>(new Map());
+  const suppressedRef = useRef(false);
+
+  const activate = useCallback((id: string) => {
+    setActiveId(id);
+    suppressedRef.current = true;
+    // Safety timeout: unsuppress if no scroll event fires (target already in view)
+    setTimeout(() => {
+      suppressedRef.current = false;
+    }, 2000);
+  }, []);
+
+  useEffect(() => {
+    const ids = headings.map((h) => h.slug);
+    headingIdsRef.current = ids;
+
+    const map = new Map<string, HTMLElement>();
+    for (const id of ids) {
+      const el = document.getElementById(id);
+      if (el) map.set(id, el);
+    }
+    elementMapRef.current = map;
+
+    let timerId: ReturnType<typeof setTimeout> | null = null;
+
+    function update() {
+      timerId = null;
+      setActiveId(
+        getActiveHeadingId(headingIdsRef.current, elementMapRef.current),
+      );
+    }
+
+    let fallbackTimerId: ReturnType<typeof setTimeout> | null = null;
+
+    function onScroll() {
+      if (suppressedRef.current) {
+        // Fallback for browsers without scrollend (Safari < 18)
+        if (fallbackTimerId !== null) clearTimeout(fallbackTimerId);
+        fallbackTimerId = setTimeout(onScrollEnd, 1500);
+        return;
+      }
+      if (timerId !== null) clearTimeout(timerId);
+      timerId = setTimeout(update, DEBOUNCE_MS);
+    }
+
+    function onScrollEnd() {
+      suppressedRef.current = false;
+      if (fallbackTimerId !== null) {
+        clearTimeout(fallbackTimerId);
+        fallbackTimerId = null;
+      }
+      if (timerId !== null) clearTimeout(timerId);
+      update();
+    }
+
+    update();
+
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll, { passive: true });
+    window.addEventListener("scrollend", onScrollEnd, { passive: true });
+
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+      window.removeEventListener("scrollend", onScrollEnd);
+      if (timerId !== null) clearTimeout(timerId);
+      if (fallbackTimerId !== null) clearTimeout(fallbackTimerId);
+    };
+  }, [headings]);
+
+  return { activeId, activate };
+}

package/templates/base/src/plugins/docs-source-map.ts

@@ -0,0 +1,103 @@
+import { readdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+export interface DocsSourceMapOptions {
+  /** Absolute root directory of the project */
+  rootDir: string;
+  /** Main docs directory relative to rootDir (e.g., "src/content/docs") */
+  docsDir: string;
+  /** Locale configurations: { ja: { dir: "src/content/docs-ja" } } */
+  locales: Record<string, { dir: string }>;
+  /** Version configurations */
+  versions: Array<{ slug: string; docsDir: string }> | false;
+  /** Base URL path (e.g., "/" or "/pj/my-docs/") */
+  base: string;
+  /** Whether to append trailing slash to URLs */
+  trailingSlash: boolean;
+}
+
+/**
+ * Build a map of absolute file paths to URL paths.
+ * Scans all configured docs directories for .md/.mdx files.
+ */
+export function buildDocsSourceMap(
+  options: DocsSourceMapOptions,
+): Map<string, string> {
+  const map = new Map<string, string>();
+  const { rootDir, docsDir, locales, versions, base, trailingSlash } = options;
+
+  const normalizedBase = base.replace(/\/+$/, "");
+
+  function applyTS(url: string): string {
+    if (trailingSlash) {
+      if (url.endsWith("/")) return url;
+      return url + "/";
+    }
+    // Strip trailing slashes when trailingSlash is false (except root "/")
+    if (url !== "/" && url.endsWith("/")) {
+      return url.replace(/\/+$/, "");
+    }
+    return url;
+  }
+
+  function withBase(path: string): string {
+    const raw =
+      normalizedBase === ""
+        ? path
+        : `${normalizedBase}${path.startsWith("/") ? path : `/${path}`}`;
+    return applyTS(raw);
+  }
+
+  function scanDir(dir: string, urlPrefix: string): void {
+    const absDir = resolve(rootDir, dir);
+    let files: string[];
+    try {
+      files = readdirSync(absDir, { recursive: true })
+        .map((f) => String(f))
+        .filter((f) => /\.(md|mdx)$/.test(f));
+    } catch {
+      // Directory doesn't exist — skip silently
+      return;
+    }
+    for (const file of files) {
+      const absFile = resolve(absDir, file);
+      // Convert file path to slug: strip extension, strip /index suffix
+      const slug = file
+        .replace(/\.(md|mdx)$/, "")
+        .replace(/(^|\/)index$/, "$1") // Strip index (root or nested)
+        .replace(/(^|\\)index$/, "$1") // Windows
+        .replace(/\\/g, "/") // Windows path sep
+        .replace(/\/$/, ""); // Trailing slash from index strip
+      const url = withBase(`${urlPrefix}/${slug}`);
+      map.set(absFile, url);
+
+      // Also register with alternative extension for cross-referencing
+      // e.g., if file is foo.mdx, also register foo.md → same URL
+      // Only set if not already registered (avoid shadowing a real file)
+      const altExt = file.endsWith(".mdx")
+        ? file.replace(/\.mdx$/, ".md")
+        : file.replace(/\.md$/, ".mdx");
+      const altFile = resolve(absDir, altExt);
+      if (!map.has(altFile)) {
+        map.set(altFile, url);
+      }
+    }
+  }
+
+  // Main docs (default locale)
+  scanDir(docsDir, "/docs");
+
+  // Locale docs
+  for (const [code, config] of Object.entries(locales)) {
+    scanDir(config.dir, `/${code}/docs`);
+  }
+
+  // Versioned docs
+  if (versions) {
+    for (const version of versions) {
+      scanDir(version.docsDir, `/v/${version.slug}/docs`);
+    }
+  }
+
+  return map;
+}

package/templates/base/src/plugins/hast-utils.ts

@@ -0,0 +1,10 @@
+import type { Element, ElementContent, Text } from "hast";
+
+/** Recursively extract plain text from a HAST node tree. */
+export function extractText(node: Element | ElementContent | Text): string {
+  if (node.type === "text") return node.value;
+  if (node.type === "element") {
+    return node.children.map((c) => extractText(c)).join("");
+  }
+  return "";
+}

package/templates/base/src/plugins/rehype-code-title.ts

@@ -0,0 +1,50 @@
+import type { Root, Element } from "hast";
+import { visit, SKIP } from "unist-util-visit";
+
+/**
+ * Rehype plugin that extracts title="..." from code block meta strings
+ * and wraps the <pre> in a container with a title header.
+ *
+ * Usage in MDX:
+ *   ```js title="config.js"
+ *   const x = 1;
+ *   ```
+ */
+export function rehypeCodeTitle() {
+  return (tree: Root) => {
+    visit(tree, "element", (node: Element, index, parent) => {
+      if (node.tagName !== "pre" || !parent || index === undefined) return;
+
+      const codeEl = node.children.find(
+        (child): child is Element =>
+          child.type === "element" && child.tagName === "code",
+      );
+      if (!codeEl) return;
+
+      const meta =
+        String(codeEl.properties?.meta ?? "") ||
+        String((codeEl.data as Record<string, unknown> | undefined)?.meta ?? "");
+      const titleMatch = meta.match(/title="([^"]+)"/);
+      if (!titleMatch) return;
+
+      const title = titleMatch[1];
+
+      const titleEl: Element = {
+        type: "element",
+        tagName: "div",
+        properties: { className: ["code-block-title"] },
+        children: [{ type: "text", value: title }],
+      };
+
+      const wrapper: Element = {
+        type: "element",
+        tagName: "div",
+        properties: { className: ["code-block-container"] },
+        children: [titleEl, { ...node }],
+      };
+
+      (parent as Element).children[index] = wrapper;
+      return SKIP;
+    });
+  };
+}

package/templates/base/src/plugins/rehype-heading-links.ts

@@ -0,0 +1,53 @@
+import type { Root, Element } from "hast";
+import GithubSlugger from "github-slugger";
+import { visit } from "unist-util-visit";
+import { extractText } from "./hast-utils";
+
+/**
+ * Rehype plugin that adds Docusaurus-style anchor links to headings (h2-h6).
+ *
+ * Generates heading IDs (via github-slugger) and appends:
+ *   <a href="#id" class="hash-link" aria-label="Direct link to ..."></a>
+ *
+ * The "#" symbol is rendered via CSS ::after to avoid polluting
+ * Astro's heading text extraction (used for TOC).
+ *
+ * Runs before Astro's built-in heading ID plugin, so it sets IDs itself.
+ * Astro's plugin will skip headings that already have an ID.
+ */
+
+const headingTags = new Set(["h2", "h3", "h4", "h5", "h6"]);
+
+export function rehypeHeadingLinks() {
+  return (tree: Root) => {
+    const slugger = new GithubSlugger();
+
+    visit(tree, "element", (node: Element) => {
+      if (!headingTags.has(node.tagName)) return;
+
+      const text = node.children
+        .map((c) => extractText(c))
+        .join("");
+
+      const id =
+        (node.properties?.id as string | undefined) || slugger.slug(text);
+
+      // Set the id if not already present
+      if (!node.properties) node.properties = {};
+      if (!node.properties.id) node.properties.id = id;
+
+      const link: Element = {
+        type: "element",
+        tagName: "a",
+        properties: {
+          href: `#${id}`,
+          className: ["hash-link"],
+          "aria-label": `Direct link to ${text}`,
+        },
+        children: [],
+      };
+
+      node.children.push(link);
+    });
+  };
+}

package/templates/base/src/plugins/rehype-image-enlarge.ts

@@ -0,0 +1,113 @@
+import type { Root, Element, ElementContent } from "hast";
+import { visit, SKIP } from "unist-util-visit";
+
+function isWhitespaceText(node: ElementContent): boolean {
+  return node.type === "text" && node.value.trim() === "";
+}
+
+function isEnlargeableFigure(node: ElementContent): boolean {
+  if (node.type !== "element" || node.tagName !== "figure") return false;
+  const cls = node.properties?.className;
+  return Array.isArray(cls) && cls.includes("zd-enlargeable");
+}
+
+function makeEnlargeButton(): Element {
+  return {
+    type: "element",
+    tagName: "button",
+    properties: {
+      type: "button",
+      className: ["zd-enlarge-btn"],
+      ariaLabel: "Enlarge image",
+      hidden: true,
+    },
+    children: [
+      {
+        type: "element",
+        tagName: "svg",
+        properties: {
+          viewBox: "0 0 38.99 38.99",
+          fill: "currentColor",
+          focusable: "false",
+          ariaHidden: true,
+        },
+        children: [
+          {
+            type: "element",
+            tagName: "polygon",
+            properties: {
+              points:
+                "16.2 13.74 5.92 3.47 11.2 3.47 11.2 0 3.47 0 0 0 0 3.47 0 11.2 3.47 11.2 3.47 5.92 13.74 16.2 16.2 13.74",
+            },
+            children: [],
+          },
+          {
+            type: "element",
+            tagName: "polygon",
+            properties: {
+              points:
+                "25.24 16.2 35.52 5.92 35.52 11.2 38.99 11.2 38.99 3.47 38.99 0 35.52 0 27.79 0 27.79 3.47 33.07 3.47 22.79 13.74 25.24 16.2",
+            },
+            children: [],
+          },
+          {
+            type: "element",
+            tagName: "polygon",
+            properties: {
+              points:
+                "22.79 25.24 33.07 35.52 27.79 35.52 27.79 38.99 35.52 38.99 38.99 38.99 38.99 35.52 38.99 27.79 35.52 27.79 35.52 33.07 25.24 22.79 22.79 25.24",
+            },
+            children: [],
+          },
+          {
+            type: "element",
+            tagName: "polygon",
+            properties: {
+              points:
+                "13.74 22.79 3.47 33.07 3.47 27.79 0 27.79 0 35.52 0 38.99 3.47 38.99 11.2 38.99 11.2 35.52 5.92 35.52 16.2 25.24 13.74 22.79",
+            },
+            children: [],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+export function rehypeImageEnlarge() {
+  return (tree: Root) => {
+    visit(tree, "element", (node: Element, index, parent) => {
+      if (node.tagName !== "p" || !parent || index === undefined) return;
+
+      const nonWs = node.children.filter((c) => !isWhitespaceText(c));
+
+      // Idempotency: <p> already contains a wrapped figure
+      if (nonWs.length === 1 && isEnlargeableFigure(nonWs[0])) return SKIP;
+
+      // Case A requires exactly one non-whitespace child that is <img>
+      if (nonWs.length !== 1) return;
+      const child = nonWs[0];
+      if (child.type !== "element" || child.tagName !== "img") return;
+
+      const imgEl = child;
+
+      // Opt-out: exact title="no-enlarge" — skip wrap but remove title attr
+      if (imgEl.properties?.title === "no-enlarge") {
+        const newProps = { ...imgEl.properties };
+        delete newProps.title;
+        imgEl.properties = newProps;
+        return SKIP;
+      }
+
+      const figureEl: Element = {
+        type: "element",
+        tagName: "figure",
+        properties: { className: ["zd-enlargeable"] },
+        children: [imgEl, makeEnlargeButton()],
+      };
+
+      (parent as Element).children[index] = figureEl;
+      return SKIP;
+    });
+  };
+}

package/templates/base/src/plugins/rehype-mermaid.ts

@@ -0,0 +1,41 @@
+import type { Root, Element } from "hast";
+import { visit } from "unist-util-visit";
+import { extractText } from "./hast-utils";
+
+/**
+ * Rehype plugin that transforms mermaid code blocks into renderable containers.
+ *
+ * After Shiki processes code blocks, mermaid blocks become:
+ *   <pre data-language="mermaid"><code><span>...</span></code></pre>
+ *
+ * This plugin converts them to:
+ *   <div class="mermaid" data-mermaid>graph LR; A-->B</div>
+ */
+
+export function rehypeMermaid() {
+  return (tree: Root) => {
+    visit(tree, "element", (node: Element, index, parent) => {
+      if (
+        node.tagName !== "pre" ||
+        !parent ||
+        index === undefined
+      ) return;
+
+      // Match Shiki-processed mermaid blocks (data-language="mermaid")
+      if (node.properties?.dataLanguage !== "mermaid") return;
+
+      // Extract all text content recursively from the code/span tree
+      const text = node.children
+        .map((c) => extractText(c))
+        .join("");
+
+      // Replace the <pre> with a <div class="mermaid">
+      (parent as Element).children[index] = {
+        type: "element",
+        tagName: "div",
+        properties: { className: ["mermaid"], "data-mermaid": true },
+        children: [{ type: "text", value: text }],
+      };
+    });
+  };
+}

package/templates/base/src/plugins/rehype-strip-md-extension.ts

@@ -0,0 +1,58 @@
+import type { Root, Element } from 'hast';
+import { visit } from 'unist-util-visit';
+import { isExternal } from './url-utils';
+
+/**
+ * Rehype plugin that strips .md/.mdx extensions from relative link hrefs
+ * and ensures they have a trailing slash for Astro's `trailingSlash: "always"` mode.
+ *
+ * Markdown authors often write links like `[Other doc](./other-doc.md)`.
+ * In Astro's static output, the correct URL is `/docs/other-doc/` (no extension).
+ *
+ * Astro 5+ may strip .md extensions before rehype runs, so this plugin also
+ * handles relative links that have already lost their extension by adding
+ * a trailing slash when the last path segment has no file extension.
+ */
+export function rehypeStripMdExtension() {
+  return (tree: Root) => {
+    visit(tree, 'element', (node: Element) => {
+      if (node.tagName !== 'a') return;
+      const href = node.properties?.href;
+      if (typeof href !== 'string') return;
+
+      // Only process relative links (not http://, https://, mailto:, #, etc.)
+      if (isExternal(href) || href.startsWith('#')) return;
+
+      let newHref = href;
+
+      // Strip .md or .mdx extension (with optional hash fragment)
+      newHref = newHref.replace(
+        /\.mdx?(#.*)?$/,
+        (_match, hash) => (hash ? '/' + hash : '/'),
+      );
+
+      // For relative links where Astro already stripped .md:
+      // add trailing slash if missing and the last segment has no file extension
+      if (newHref === href && (newHref.startsWith('./') || newHref.startsWith('../'))) {
+        // Split off query string and hash fragment
+        const qIdx = newHref.indexOf('?');
+        const hIdx = newHref.indexOf('#');
+        const suffixIdx = qIdx >= 0 ? qIdx : hIdx >= 0 ? hIdx : -1;
+        const path = suffixIdx >= 0 ? newHref.slice(0, suffixIdx) : newHref;
+        const suffix = suffixIdx >= 0 ? newHref.slice(suffixIdx) : '';
+
+        if (!path.endsWith('/')) {
+          const lastSegment = path.split('/').pop() || '';
+          // Only add slash if there's no file extension (like .png, .pdf, etc.)
+          if (!/\.[a-zA-Z]\w*$/.test(lastSegment)) {
+            newHref = path + '/' + suffix;
+          }
+        }
+      }
+
+      if (newHref !== href) {
+        node.properties.href = newHref;
+      }
+    });
+  };
+}