create-zudo-doc 5.24.1 → 5.25.0

package/CHANGELOG.md

@@ -8,6 +8,23 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 No unreleased changes.
 
+## [5.25.0] - 2026-09-16
+
+### Bug Fixes
+
+- The generated `scripts/check-links.js`'s MDX id scan no longer lets an escaped `\<` in prose start a fake tag that swallows a later element's static `id` across a blank line, wrongly reporting a valid anchor as broken. Projects that copied `scripts/check-links.js` from the template can re-copy it to pick up the fix. (0ea5eeae6)
+
+### Other Changes
+
+- New scaffolds no longer add a `.zudo-doc/` entry to the generated `.gitignore`. The staging step it was for was removed from `@takazudo/zudo-doc`'s route injection — see that package's changelog. (54a3f12a9)
+- Generated projects now pin `@takazudo/zfb`, `@takazudo/zfb-runtime`, and `@takazudo/zfb-md-wasm` to `2.18.0` (e4d4b64b3). That release reworks package-injected routes and plugin virtual modules and changes no API, export, or config default, so existing projects need no migration.
+
+## [5.24.2] - 2026-09-15
+
+### Bug Fixes
+
+- Generated projects list `diff` only when doc history is enabled (directly, or through `bodyFootUtil`), and no longer list `katex` by default. Projects that turn on `math: true` install `katex` themselves (`pnpm add katex`). (c778ca989)
+
 ## [5.24.1] - 2026-09-15
 
 ### Other Changes

package/dist/scaffold.d.ts

@@ -31,5 +31,5 @@ export declare function deriveDocSkillName(projectName: string): string;
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export declare const ZUDO_DOC_PIN = "^5.24.1";
+export declare const ZUDO_DOC_PIN = "^5.25.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -47,7 +47,7 @@ export function deriveDocSkillName(projectName) {
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^5.24.1";
+export const ZUDO_DOC_PIN = "^5.25.0";
 /**
  * Files in `templates/base/**` that must not be copied by the unconditional
  * base mirror. Each entry is matched against the path relative to
@@ -466,9 +466,6 @@ export async function scaffold(choices) {
         "# Cloudflare Wrangler",
         ".wrangler/",
         "",
-        "# zudo-doc build artifact (routes-src/ staged here at build time)",
-        ".zudo-doc/",
-        "",
     ];
     // The doc-lookup skill is only generated when skillSymlinker is selected
     // (the setup-doc-skill.sh script and `setup:doc-skill` npm script are gated
@@ -778,9 +775,17 @@ function generatePackageJson(choices, localePlan) {
         // moved sizes; zfb-runtime and zfb-adapter-cloudflare change only their
         // README/description. No public API, export, config default, or engine
         // requirement moves, so a fresh scaffold needs no migration.
-        "@takazudo/zfb": "2.17.0",
-        "@takazudo/zfb-runtime": "2.17.0",
-        "@takazudo/zfb-md-wasm": "2.17.0",
+        // 2.18.0: zfb reworks package-injected routes and plugin virtual modules —
+        // the islands scanner now resolves plugin virtual modules and is seeded with
+        // package-route entrypoints, dev CSS content globs are seeded from injected
+        // routes, injected-route entrypoints and their import closure are staged as
+        // exact files, and SSR virtual modules may import those canonical files while
+        // the hidden-path guard still holds. zfb-runtime, zfb-adapter-cloudflare, and
+        // md-wasm carry no package-specific change. No public API, export, config
+        // default, or engine requirement moves, so a fresh scaffold needs no migration.
+        "@takazudo/zfb": "2.18.0",
+        "@takazudo/zfb-runtime": "2.18.0",
+        "@takazudo/zfb-md-wasm": "2.18.0",
         // @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
@@ -821,25 +826,16 @@ function generatePackageJson(choices, localePlan) {
         // compiles. Same pin as host. Caught by W6B (#1735) consumer-build
         // verification.
         "preact-render-to-string": "^6.6.6",
-        // katex — server-side LaTeX renderer used by the always-on
-        // pages/lib/_math-block.tsx (called from pages/_mdx-components.ts
-        // for `$…$` and `$$…$$` math nodes). Caught by W6B (#1735)
-        // consumer-build verification — the import lives in the mirrored
-        // pages, not behind any feature gate. Same pin as host.
-        katex: "^0.16.38",
-        // diff — required at build time by EVERY generated project, not just
-        // docHistory ones. The always-copied host base template
-        // `pages/lib/_doc-history-area.tsx` statically imports the real
-        // `DocHistory` from `@takazudo/zudo-doc/doc-history` (to keep zfb's island
-        // scanner chain page→stub→DocHistory walkable), which pulls
-        // `@takazudo/zudo-doc/dist/doc-history/index.js`'s `await import("diff")`
-        // into the bundle. With packageOwnedRoutes default ON (1.0), a
-        // docHistory-off project still bundles that path, so without `diff` here
-        // `zfb build` fails at esbuild with "Could not resolve 'diff'" (#2342).
-        // `diff` is an *optional* peerDependency of @takazudo/zudo-doc, so a
-        // missing copy produces no `pnpm install` warning — which is why this gap
-        // shipped silently and only surfaced at build time.
-        diff: "^8.0.3",
+        // katex is intentionally ABSENT here. `math` is not a create-zudo-doc
+        // feature (it defaults to `false` in DEFAULT_SETTINGS) and
+        // @takazudo/zudo-doc now loads katex via a rejection-handled dynamic
+        // import that stays non-build-fatal when the package is absent (#4206 /
+        // #4209). A project that turns `math: true` on by hand must
+        // `pnpm add katex` itself — see the math-equations doc.
+        // diff is likewise intentionally ABSENT from this unconditional block —
+        // it is added below, gated on the docHistory feature, for the same
+        // #4206 / #4209 reason: the doc-history route's `import("diff")` is now
+        // rejection-handled instead of build-fatal when docHistory is off.
         // (@takazudo/zdtp is NOT here — it is gated on the designTokenPanel
         // feature, see the block below. It WAS unconditional from #2660 through
         // #4018: `chrome/derive.tsx`'s `deriveBodyEndIslands` statically imports
@@ -881,6 +877,17 @@ function generatePackageJson(choices, localePlan) {
     // search ships as @takazudo/zudo-doc's own self-contained generated
     // search-widget script (custom word-match scorer) — no third-party search
     // engine dependency is needed here. Do not re-add minisearch/pagefind.
+    if (choices.features.includes("docHistory")) {
+        // diff powers the History dropdown's Compare view
+        // (`@takazudo/zudo-doc/doc-history`'s `await import("diff")`). #4209 made
+        // that import rejection-handled, so a docHistory-OFF project no longer
+        // needs the dep at all — including bodyFootUtil-only projects, since
+        // scaffold() already normalizes bodyFootUtil into docHistory before this
+        // function runs (see the co-enable block near the top of scaffold()).
+        // assetViewer alone does not reach this import and must not carry it
+        // (#4206 / #4209; it was an unconditional base dep before this fix).
+        deps.diff = "^8.0.3";
+    }
     if (choices.features.includes("designTokenPanel")) {
         // Only the design-token-panel feature graph reaches @takazudo/zdtp: the
         // panel payload loads through a rejection-handled `import("@takazudo/zdtp")`
@@ -892,9 +899,9 @@ function generatePackageJson(choices, localePlan) {
     }
     if (choices.features.includes("docHistory") ||
         choices.features.includes("assetViewer")) {
-        // (`diff` remains an unconditional base dep — see the `deps` block above:
-        // packageOwnedRoutes always bundles the doc-history-area path, whose
-        // module-scope `diff` import is pulled in regardless of this flag. #2342.)
+        // (`diff` is gated separately, on docHistory alone — see the block just
+        // above this one. assetViewer does not reach the Compare view's
+        // `import("diff")`, so it must not add the dep on its own; #4206 / #4209.)
         //
         // @takazudo/zudo-doc-history-server is gated HERE because docHistory and
         // assetViewer are the only feature graphs that reach it. The doc-history
@@ -911,7 +918,7 @@ function generatePackageJson(choices, localePlan) {
         // `/exclude` at module scope from the always-bundled chrome graph; #3110
         // moved compileExclude into @takazudo/zudo-doc, so projects with both
         // docHistory and assetViewer off no longer need the package at all.
-        deps["@takazudo/zudo-doc-history-server"] = "^5.24.1";
+        deps["@takazudo/zudo-doc-history-server"] = "^5.25.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/package.json

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

package/templates/base/scripts/check-links.js

@@ -663,8 +663,27 @@ function extractStaticMdxIds(body) {
   // (#4048). The rest of this pattern keeps its own semantics — `\bid` also
   // accepts `data-id`, and only non-empty quoted values count, unlike the
   // built-HTML id scan.
+  //
+  // Two extra guards, scoped to this MDX scan only (the shared
+  // HTML_ATTRIBUTE_RUN above is untouched — the built-HTML scans still rely on
+  // multi-line quoted attributes):
+  //
+  // - MDX_UNESCAPED_LT_LOOKBEHIND: an escaped `\<` in prose is valid MDX and
+  //   must not start a fake tag. Parity matters, not just "preceded by a
+  //   backslash" — `\\<` is an escaped backslash followed by an active `<`.
+  //   The lookbehind is anchored at the run's start (`(?<!\\)`) so it judges
+  //   the whole contiguous backslash run, not a suffix of it.
+  // - MDX_ID_ATTRIBUTE_RUN: without this, a fake tag opened by an escaped `<`
+  //   can have prose apostrophes read as a `'...'` quoted value that crosses
+  //   a real `>` and swallows a real element's id on a later line (#4218).
+  //   Disallowing a blank line inside a quoted value bounds the damage to a
+  //   single paragraph while still letting a real JSX tag — including a
+  //   quoted value spanning one newline — match.
+  const MDX_UNESCAPED_LT_LOOKBEHIND = /(?<!(?<!\\)(?:\\\\)*\\)/.source;
+  const MDX_ID_ATTRIBUTE_RUN =
+    /(?:"(?:(?!\r?\n[ \t]*\r?\n)[^"])*"|'(?:(?!\r?\n[ \t]*\r?\n)[^'])*'|[^>"'])/.source;
   const regex = new RegExp(
-    `<[A-Za-z]${HTML_ATTRIBUTE_RUN}*?\\bid\\s*=\\s*(?:"([^"]+)"|'([^']+)')${HTML_ATTRIBUTE_RUN}*>`,
+    `${MDX_UNESCAPED_LT_LOOKBEHIND}<[A-Za-z]${MDX_ID_ATTRIBUTE_RUN}*?\\bid\\s*=\\s*(?:"([^"]+)"|'([^']+)')${MDX_ID_ATTRIBUTE_RUN}*>`,
     "gs",
   );
   let match;