create-zudo-doc 3.1.0 → 3.2.0

package/dist/preset.d.ts

@@ -38,6 +38,7 @@ export interface PresetJson {
     features?: string[];
     githubUrl?: string;
     cjkFriendly?: boolean;
+    minifyHtml?: boolean;
     packageManager?: "pnpm" | "npm" | "yarn" | "bun";
     headerRightItems?: PresetHeaderRightItem[];
     metaTags?: PresetMetaTagsConfig;

package/dist/preset.js

@@ -72,6 +72,9 @@ export function validatePreset(json) {
     if (p.cjkFriendly !== undefined && typeof p.cjkFriendly !== "boolean") {
         return `"cjkFriendly" must be a boolean in preset`;
     }
+    if (p.minifyHtml !== undefined && typeof p.minifyHtml !== "boolean") {
+        return `"minifyHtml" must be a boolean in preset`;
+    }
     if (p.headerRightItems !== undefined) {
         if (!Array.isArray(p.headerRightItems)) {
             return `"headerRightItems" must be an array in preset`;
@@ -177,6 +180,8 @@ export function presetToChoices(json) {
         choices.githubUrl = json.githubUrl;
     if (json.cjkFriendly !== undefined)
         choices.cjkFriendly = json.cjkFriendly;
+    if (json.minifyHtml !== undefined)
+        choices.minifyHtml = json.minifyHtml;
     if (json.headerRightItems !== undefined) {
         choices.headerRightItems = json.headerRightItems;
     }

package/dist/prompts.d.ts

@@ -12,6 +12,7 @@ export interface UserChoices {
     explicitlyDisabledFeatures?: string[];
     githubUrl?: string;
     cjkFriendly?: boolean;
+    minifyHtml?: boolean;
     packageManager: "pnpm" | "npm" | "yarn" | "bun";
     headerRightItems?: PresetHeaderRightItem[];
     metaTags?: PresetMetaTagsConfig;
@@ -29,6 +30,7 @@ export interface PartialChoices {
     explicitlyDisabledFeatures?: string[];
     githubUrl?: string;
     cjkFriendly?: boolean;
+    minifyHtml?: boolean;
     packageManager?: "pnpm" | "npm" | "yarn" | "bun";
     headerRightItems?: PresetHeaderRightItem[];
     metaTags?: PresetMetaTagsConfig;

package/dist/prompts.js

@@ -200,6 +200,7 @@ export async function runPrompts(prefilled = {}) {
         explicitlyDisabledFeatures: prefilled.explicitlyDisabledFeatures,
         githubUrl,
         cjkFriendly: prefilled.cjkFriendly,
+        minifyHtml: prefilled.minifyHtml,
         packageManager,
         headerRightItems: prefilled.headerRightItems,
         metaTags: prefilled.metaTags,

package/dist/scaffold.d.ts

@@ -11,5 +11,5 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export declare const ZUDO_DOC_PIN = "^3.1.0";
+export declare const ZUDO_DOC_PIN = "^3.2.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -18,11 +18,11 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^3.1.0";
+export const ZUDO_DOC_PIN = "^3.2.0";
 /**
- * Files in `templates/base/**` that must never be copied into a generated
- * project. Each entry is matched against the path relative to `templates/base/`
- * (POSIX-style, forward slashes).
+ * Files in `templates/base/**` that must not be copied by the unconditional
+ * base mirror. Each entry is matched against the path relative to
+ * `templates/base/` (POSIX-style, forward slashes).
  *
  * W2 spec-lock Decision 5 (#1728) — `pages/api/**` is worker-only SSR
  * (uses `@takazudo/zfb-adapter-cloudflare`, `prerender = false`) and is
@@ -32,6 +32,7 @@ export const ZUDO_DOC_PIN = "^3.1.0";
  */
 const EXCLUDE_FROM_MIRROR = [
     /^pages\/api(\/|$)/,
+    /^scripts\/setup-doc-skill\.sh$/,
 ];
 /**
  * `fs.copy` filter for the `templates/base/` → target-dir copy. Returns
@@ -201,7 +202,7 @@ export async function scaffold(choices) {
     const templatesDir = path.join(pkgRoot, "templates");
     const baseDir = path.join(templatesDir, "base");
     const featuresDir = path.join(templatesDir, "features");
-    // For skillSymlinker, we still need the monorepo root for the script
+    // Still needed for source-checkout-only assets such as Claude skills.
     const monorepoRoot = path.resolve(pkgRoot, "../..");
     await fs.ensureDir(targetDir);
     // 1. Copy base template
@@ -214,11 +215,9 @@ export async function scaffold(choices) {
     });
     // 2. Copy skill symlinker script when enabled
     if (choices.features.includes("skillSymlinker")) {
-        const scriptSrc = path.join(monorepoRoot, "scripts/setup-doc-skill.sh");
+        const scriptSrc = path.join(baseDir, "scripts/setup-doc-skill.sh");
         const scriptDest = path.join(targetDir, "scripts/setup-doc-skill.sh");
-        if (await fs.pathExists(scriptSrc)) {
-            await fs.copy(scriptSrc, scriptDest);
-        }
+        await fs.copy(scriptSrc, scriptDest);
     }
     // 2b. Copy user-facing Claude Code skills when enabled
     // Ships the curated zudo-doc-* skills (design-system, translate, version-bump)
@@ -497,14 +496,15 @@ function generatePackageJson(choices) {
         // pins. No consumer-facing / CLI change.
         // next.76: routine toolchain bump from next.75, adopted in
         // lockstep with the root package.json pins. No consumer-facing / CLI change.
-        // next.77 (current pin): router persistence/history fixes and runtime
-        // island remount support, adopted in lockstep with the root package.json
-        // pins. No scaffold API change.
-        "@takazudo/zfb": "0.1.0-next.77",
-        "@takazudo/zfb-runtime": "0.1.0-next.77",
+        // next.77: router persistence/history fixes and runtime island remount
+        // support, adopted in lockstep with the root package.json pins. No
+        // scaffold API change. next.78 (current pin): production HTML minification
+        // support via minifyHtml, adopted as a zudo-doc default through settings.
+        "@takazudo/zfb": "0.1.0-next.78",
+        "@takazudo/zfb-runtime": "0.1.0-next.78",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.77",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.78",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
@@ -587,7 +587,7 @@ function generatePackageJson(choices) {
         // @takazudo/zudo-doc/integrations/doc-history which in turn imports
         // @takazudo/zudo-doc-history-server/git-history. Without this dep the
         // plugin host fails at init with ERR_MODULE_NOT_FOUND — W8A (#1739).
-        deps["@takazudo/zudo-doc-history-server"] = "^3.1.0";
+        deps["@takazudo/zudo-doc-history-server"] = "^3.2.0";
         // tsx is no longer needed here: the relocated package plugin imports the
         // runner directly (no `tsx -e` spawn) since the package ships compiled
         // dist/ — package-first migration #2321 (#2337).

package/dist/settings-gen.js

@@ -51,6 +51,7 @@ export function generateSettingsFile(choices) {
     lines.push(`  siteDescription: "" as string,`);
     lines.push(`  base: "/",`);
     lines.push(`  trailingSlash: false as boolean,`);
+    lines.push(`  minifyHtml: ${choices.minifyHtml ?? true} as boolean,`);
     lines.push(`  noindex: ${choices.features.includes("noindex")} as boolean,`);
     lines.push(`  editUrl: false as string | false,`);
     const rawGithubUrl = (choices.githubUrl ?? "").trim();

package/dist/zfb-config-gen.d.ts

@@ -4,8 +4,8 @@ import type { UserChoices } from "./prompts.js";
  *
  * S5b (#2329): collapsed to the thin preset-based shape that mirrors the
  * showcase `zfb.config.ts` after S5a. All collection wiring, plugin
- * descriptors, markdown features, codeHighlight, resolveMarkdownLinks, and
- * trailingSlash are now owned by `zudoDocPreset()` in
+ * descriptors, markdown features, codeHighlight, resolveMarkdownLinks,
+ * trailingSlash, and minifyHtml are now owned by `zudoDocPreset()` in
  * `@takazudo/zudo-doc/preset`. The generated config spreads the preset
  * result into `defineConfig` and keeps only the project-owned shell fields
  * (`framework`, `port`, `tailwind`, `base`).

package/dist/zfb-config-gen.js

@@ -3,8 +3,8 @@
  *
  * S5b (#2329): collapsed to the thin preset-based shape that mirrors the
  * showcase `zfb.config.ts` after S5a. All collection wiring, plugin
- * descriptors, markdown features, codeHighlight, resolveMarkdownLinks, and
- * trailingSlash are now owned by `zudoDocPreset()` in
+ * descriptors, markdown features, codeHighlight, resolveMarkdownLinks,
+ * trailingSlash, and minifyHtml are now owned by `zudoDocPreset()` in
  * `@takazudo/zudo-doc/preset`. The generated config spreads the preset
  * result into `defineConfig` and keeps only the project-owned shell fields
  * (`framework`, `port`, `tailwind`, `base`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/scripts/setup-doc-skill.sh

@@ -0,0 +1,261 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ── setup-doc-skill.sh ─────────────────────────────────
+# Creates an agent skill that exposes your zudo-doc
+# documentation as a knowledge base, then symlinks it into
+# the user-scope skills directory (~/.claude/skills/ and/or
+# ~/.codex/skills/).
+# ────────────────────────────────────────────────────────
+
+TARGET_MODE="auto"
+
+# Accept --silent (alias -y) for parity with the consuming-site convention:
+# scaffolded sites expose `setup:doc-skill-silent` = `bash scripts/setup-doc-skill.sh
+# --silent`. This script is already non-interactive (the skill name is deterministic
+# — see below), so the flag is a no-op here; it is consumed only so it is never
+# mistaken for the positional skill-name override (`$1`).
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --silent|-y) shift ;;
+    --target)
+      shift
+      if [ $# -eq 0 ]; then
+        echo "Error: --target requires one of: auto, claude, codex, both" >&2
+        exit 1
+      fi
+      TARGET_MODE="$1"
+      shift
+      ;;
+    --target=*)
+      TARGET_MODE="${1#--target=}"
+      shift
+      ;;
+    --) shift; break ;;
+    -*) echo "Error: unknown flag '$1'" >&2; exit 1 ;;
+    *) break ;;
+  esac
+done
+
+case "$TARGET_MODE" in
+  auto|claude|codex|both) ;;
+  *)
+    echo "Error: --target must be one of: auto, claude, codex, both" >&2
+    exit 1
+    ;;
+esac
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Read project name from package.json
+PROJECT_NAME=$(node -e "console.log(require('$ROOT_DIR/package.json').name || 'my-project')")
+DEFAULT_SKILL_NAME="${PROJECT_NAME}-wisdom"
+
+echo ""
+echo "=== zudo-doc Skill Setup ==="
+echo ""
+
+# Skill name is DETERMINISTIC: always `<projectName>-wisdom`. The scaffolded
+# .gitignore (emitted by create-zudo-doc) hard-codes this exact name, so the
+# generated skill directory must match it — an interactive prompt would let the
+# name drift from the gitignore entry and leave the skill showing as untracked
+# (zudolab/zudo-doc#2173). An explicit override is still allowed via the first
+# CLI arg or the SKILL_NAME env var (consumers who override must also update
+# their .gitignore), but never via an interactive prompt.
+SKILL_NAME="${1:-${SKILL_NAME:-$DEFAULT_SKILL_NAME}}"
+
+# Validate skill name (allow only alphanumeric, hyphens, underscores)
+if [[ ! "$SKILL_NAME" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+  echo "Error: Skill name may only contain letters, numbers, hyphens, and underscores."
+  exit 1
+fi
+
+# Resolve the main repo root (handles git worktrees correctly)
+# Use the main worktree path so symlinks survive worktree removal
+REPO_ROOT="$(git -C "$ROOT_DIR" worktree list | head -1 | awk '{print $1}')"
+
+DOCS_DIR="$ROOT_DIR/src/content/docs"
+
+# Validate docs directory exists
+if [ ! -d "$DOCS_DIR" ]; then
+  echo "Error: Documentation directory not found at $DOCS_DIR"
+  exit 1
+fi
+
+# Helper: replace a symlink or file at the given path
+ensure_symlink() {
+  local link_path="$1"
+  local target="$2"
+  if [ -L "$link_path" ] || [ -e "$link_path" ]; then
+    rm -rf "$link_path"
+  fi
+  ln -s "$target" "$link_path"
+}
+
+DOCS_JA_DIR="$ROOT_DIR/src/content/docs-ja"
+HAS_JA=""
+if [ -d "$DOCS_JA_DIR" ]; then
+  HAS_JA="true"
+fi
+
+# Discover top-level doc categories dynamically
+DOC_TREE=""
+for dir in "$DOCS_DIR"/*/; do
+  [ -d "$dir" ] || continue
+  dirname="$(basename "$dir")"
+  DOC_TREE="${DOC_TREE}- ${dirname}/
+"
+done
+
+resolve_targets() {
+  case "$TARGET_MODE" in
+    claude) echo "claude" ;;
+    codex) echo "codex" ;;
+    both) echo "claude codex" ;;
+    auto)
+      local has_claude=""
+      local has_codex=""
+      [ -d "$HOME/.claude" ] && has_claude="true"
+      [ -d "$HOME/.codex" ] && has_codex="true"
+
+      if [ "$has_claude" = "true" ] && [ "$has_codex" = "true" ]; then
+        echo "claude codex"
+      elif [ "$has_codex" = "true" ]; then
+        echo "codex"
+      else
+        # Preserve the historical default for fresh machines and test homes.
+        echo "claude"
+      fi
+      ;;
+  esac
+}
+
+generate_skill() {
+  local target="$1"
+  local project_skills_dir="$ROOT_DIR/.$target/skills"
+  local skill_dir="$project_skills_dir/$SKILL_NAME"
+  local global_skills_dir="$HOME/.$target/skills"
+  local assistant_label
+
+  case "$target" in
+    claude) assistant_label="Claude Code" ;;
+    codex) assistant_label="Codex" ;;
+    *) echo "Error: unknown target '$target'" >&2; exit 1 ;;
+  esac
+
+  mkdir -p "$skill_dir"
+
+  ensure_symlink "$skill_dir/docs" "$REPO_ROOT/src/content/docs"
+  echo "  [$target] Created docs symlink -> $REPO_ROOT/src/content/docs"
+
+  if [ "$HAS_JA" = "true" ]; then
+    ensure_symlink "$skill_dir/docs-ja" "$REPO_ROOT/src/content/docs-ja"
+    echo "  [$target] Created docs-ja symlink -> $REPO_ROOT/src/content/docs-ja"
+  fi
+
+  cat > "$skill_dir/SKILL.md" << SKILLEOF
+---
+name: $SKILL_NAME
+description: >-
+  Search and reference documentation from the $PROJECT_NAME project.
+  Use when answering questions about $PROJECT_NAME features, configuration,
+  components, or usage patterns.
+user-invocable: true
+argument-hint: "[-u|--update] [topic keyword, e.g., 'configuration', 'sidebar', 'i18n']"
+---
+
+# $PROJECT_NAME Documentation Reference
+
+Look up documentation from the $PROJECT_NAME project for $assistant_label.
+Documentation base path: \`src/content/docs\` (relative to repo root)
+
+## Mode Detection
+
+Parse the argument string for flags:
+
+- If args start with \`-u\` or \`--update\`: enter **Update mode** (see below)
+- Otherwise: enter **Lookup mode** (default)
+
+Strip the flag from the remaining argument to get the topic keyword.
+
+## Lookup Mode (default)
+
+1. Find the relevant article(s) from the \`docs/\` directory based on the topic
+2. Read ONLY the specific article(s) you need — do NOT load all articles at once
+3. Apply the information from the article when answering the user's question
+4. Mention the source article path so the user can find it for further reading
+
+## Update Mode (\`-u\` / \`--update\`)
+
+The user has new information and wants to add or update documentation in this repo.
+
+### Workflow
+
+1. **Understand the new info**: Ask the user what they learned or want to
+   document. The topic keyword (if provided) hints at the subject area.
+2. **Find existing docs**: Search the \`docs/\` directory for articles related to
+   the topic. Read them to understand what is already covered.
+3. **Decide create vs update**: If an existing article covers the topic, update
+   it. Otherwise, create a new \`.mdx\` file in the appropriate subdirectory.
+4. **Write the content**: Follow the doc-authoring rules in the root CLAUDE.md:
+   - Required frontmatter: \`title\` (string). Always set \`sidebar_position\`.
+     Optional: \`description\`, \`sidebar_label\`, \`tags\`, etc.
+   - Do NOT use \`# h1\` in content — the frontmatter \`title\` renders as h1.
+     Start with \`## h2\` headings.
+   - Use available MDX components (\`<Note>\`, \`<Tip>\`, \`<Info>\`, \`<Warning>\`,
+     \`<Danger>\`, \`<HtmlPreview>\`) where appropriate.
+   - For live demos, use \`<HtmlPreview>\` with \`js\`/\`displayJs\` props.
+   - Link to other docs using relative paths with \`.mdx\` extension.
+5. **Update Japanese docs**: Create or update the corresponding file under
+   \`docs-ja/\` mirroring the English directory structure. Keep code blocks,
+   Mermaid diagrams, and \`<HtmlPreview>\` blocks identical — only translate
+   surrounding prose. Exception: pages with \`generated: true\` skip translation.
+6. **Format**: Run \`pnpm format:md\` to format the new/changed MDX files.
+7. **Verify**: Run \`pnpm build\` to confirm the site builds correctly.
+
+## Documentation Structure
+
+The documentation is organized in MDX files under \`docs/\`:
+
+\`\`\`
+${DOC_TREE}\`\`\`
+
+Browse the \`docs/\` directory to discover available articles. Each \`.mdx\` file
+has YAML frontmatter with \`title\` and \`description\` fields that help identify
+the right article to read.
+SKILLEOF
+
+  if [ "$HAS_JA" = "true" ]; then
+    cat >> "$skill_dir/SKILL.md" << JAEOF
+
+## Japanese Documentation
+
+Japanese translations are available under \`docs-ja/\`. When the user is working
+in Japanese or asks for Japanese content, prefer articles from \`docs-ja/\`.
+JAEOF
+  fi
+
+  echo "  [$target] Generated SKILL.md"
+
+  mkdir -p "$global_skills_dir"
+  ensure_symlink "$global_skills_dir/$SKILL_NAME" "$skill_dir"
+
+  echo "  [$target] Project skill: $skill_dir"
+  echo "  [$target] Global symlink: $global_skills_dir/$SKILL_NAME"
+}
+
+read -r -a TARGETS <<< "$(resolve_targets)"
+echo "Target: $TARGET_MODE -> ${TARGETS[*]}"
+echo ""
+
+for target in "${TARGETS[@]}"; do
+  generate_skill "$target"
+done
+
+echo ""
+echo "Done! Skill '$SKILL_NAME' is ready."
+echo ""
+echo "Use --target claude, --target codex, or --target both to override auto-detection."
+echo "In Claude Code, use: /$SKILL_NAME <topic>"
+echo "In Codex, mention the skill by name when asking about this documentation."
+echo ""

package/templates/base/zfb-shim.d.ts

@@ -152,6 +152,11 @@ declare module "zfb/config" {
      * haven't opted in.
      */
     trailingSlash?: boolean;
+    /**
+     * Minify production HTML output from `zfb build`.
+     * Mirrors `Config::minify_html` in crates/zfb/src/config.rs.
+     */
+    minifyHtml?: boolean;
     /**
      * Markdown / MDX pipeline options. Mirrors `Config::markdown` →
      * `MarkdownConfig` in crates/zfb/src/config.rs. zfb next.12 moved the