create-zudo-doc 0.2.0 → 0.2.2

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

@@ -1,133 +0,0 @@
-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

@@ -1,103 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

@@ -1,50 +0,0 @@
-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

@@ -1,53 +0,0 @@
-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
- * heading text extraction (used for TOC).
- *
- * Sets heading IDs itself (via github-slugger); skips headings that already
- * have an ID assigned upstream.
- */
-
-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-mermaid.ts

@@ -1,41 +0,0 @@
-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/url-utils.ts

@@ -1,4 +0,0 @@
-/** Check if a URL is external (has a protocol scheme). */
-export function isExternal(url: string): boolean {
-  return /^[a-z][a-z0-9+.-]*:/i.test(url);
-}

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

@@ -1,24 +0,0 @@
-/**
- * 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/features/docHistory/files/src/utils/doc-history.ts

@@ -1,180 +0,0 @@
-import { execFileSync } from "node:child_process";
-import path from "node:path";
-import type { DocHistoryEntry, DocHistoryData } from "@/types/doc-history";
-import { collectMdFiles } from "./content-files";
-
-/** Shared options to suppress git stderr noise */
-const QUIET: { encoding: "utf-8"; stdio: ["pipe", "pipe", "pipe"] } = {
-  encoding: "utf-8",
-  stdio: ["pipe", "pipe", "pipe"],
-};
-
-/** Cache the repo root to avoid repeated git calls */
-let repoRootCache: string | null = null;
-
-function getRepoRoot(): string {
-  if (repoRootCache) return repoRootCache;
-  repoRootCache = execFileSync("git", ["rev-parse", "--show-toplevel"], {
-    encoding: "utf-8",
-  }).trim();
-  return repoRootCache;
-}
-
-/** Convert an absolute path to a repo-relative path for git commands */
-function toRepoRelative(absolutePath: string): string {
-  return path.relative(getRepoRoot(), absolutePath);
-}
-
-/**
- * Get the list of commit hashes that touched a file, newest first.
- * Uses --follow to track renames.
- * Limits to maxEntries commits (default 50).
- */
-export function getFileCommits(
-  filePath: string,
-  maxEntries = 50,
-): string[] {
-  try {
-    const output = execFileSync(
-      "git",
-      [
-        "log",
-        "--follow",
-        "--format=%H",
-        "-n",
-        String(maxEntries),
-        "--",
-        filePath,
-      ],
-      QUIET,
-    ).trim();
-    return output ? [...new Set(output.split("\n"))] : [];
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Get metadata for a specific commit on a file.
- * Returns { hash, date, author, message } with full hash for unique identification.
- */
-export function getCommitInfo(
-  hash: string,
-  filePath: string,
-): Omit<DocHistoryEntry, "content"> {
-  try {
-    const output = execFileSync(
-      "git",
-      ["log", "-1", "--format=%H%n%aI%n%aN%n%s", hash, "--", filePath],
-      QUIET,
-    ).trim();
-    const lines = output.split("\n");
-    return {
-      hash: lines[0] ?? hash,
-      date: lines[1] ?? "",
-      author: lines[2] ?? "",
-      message: lines[3] ?? "",
-    };
-  } catch {
-    return { hash, date: "", author: "", message: "" };
-  }
-}
-
-/**
- * Get the file content at a specific commit.
- * Accepts absolute paths and converts to repo-relative for git show.
- * Handles renamed files by falling back to the old path via git log --follow.
- */
-export function getFileAtCommit(hash: string, filePath: string): string {
-  const relPath = path.isAbsolute(filePath)
-    ? toRepoRelative(filePath)
-    : filePath;
-
-  try {
-    return execFileSync("git", ["show", `${hash}:${relPath}`], QUIET);
-  } catch {
-    // File may have been renamed — find the old path at this commit
-    try {
-      const oldPath = execFileSync(
-        "git",
-        [
-          "log",
-          "-1",
-          "--follow",
-          "--diff-filter=R",
-          "--format=",
-          "--name-only",
-          hash,
-          "--",
-          relPath,
-        ],
-        QUIET,
-      ).trim();
-      if (oldPath) {
-        return execFileSync("git", ["show", `${hash}:${oldPath}`], QUIET);
-      }
-    } catch {
-      // ignore
-    }
-
-    // Last resort: use git log --follow to find the path at this revision
-    try {
-      const followOutput = execFileSync(
-        "git",
-        [
-          "log",
-          "--follow",
-          "--format=%H",
-          "--name-only",
-          "--diff-filter=AMRC",
-          "--",
-          relPath,
-        ],
-        QUIET,
-      ).trim();
-      const lines = followOutput.split("\n").filter(Boolean);
-      // Lines alternate: hash, filename, hash, filename...
-      for (let i = 0; i < lines.length - 1; i += 2) {
-        if (lines[i] === hash && lines[i + 1]) {
-          return execFileSync(
-            "git",
-            ["show", `${hash}:${lines[i + 1]}`],
-            QUIET,
-          );
-        }
-      }
-    } catch {
-      // ignore
-    }
-
-    return "";
-  }
-}
-
-/**
- * Get the complete history for a document file.
- * Returns DocHistoryData with all entries populated.
- */
-export function getDocHistory(
-  filePath: string,
-  slug: string,
-  maxEntries = 50,
-): DocHistoryData {
-  const commits = getFileCommits(filePath, maxEntries);
-  const entries: DocHistoryEntry[] = commits.map((hash) => {
-    const info = getCommitInfo(hash, filePath);
-    const content = getFileAtCommit(hash, filePath);
-    return { ...info, content };
-  });
-  return { slug, filePath, entries };
-}
-
-/**
- * Collect all MDX/md files in a content directory.
- * Delegates to the shared collectMdFiles utility from content-files.ts.
- */
-export function collectContentFiles(
-  contentDir: string,
-): Array<{ filePath: string; slug: string }> {
-  return collectMdFiles(contentDir);
-}