vitepress-allyouneed 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/);版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## [0.5.2] - 2026-06-20
+
+实战(90 页 DE+ZH 物理知识库,重 KaTeX / Wikilink / GFM 表格)发现的三个 build-blocker / 死链 bug,纯插件侧可修,无需改任何内容。
+
+### Fixed
+- **致命崩溃(同 0.5.1 那类 `state.pos`,但这次出在 `#tag` inline rule):`vitepress build` 在含 `#tag` 的 link label / 嵌套方括号 / GFM 表格单元格上整站构建失败**,报 `inline rule didn't increment state.pos`。
+  - 根因:`modules/tags/rule.ts` 的 `#tag` inline rule 注册在 `link` 之前;markdown-it 的 link 核心规则用 `parseLinkLabel → skipToken` 以 **silent 模式**扫描 `[...]` label,本规则在 silent 下 `return true` 却**没推进 `state.pos`**,触发 markdown-it 的安全检查并经 `parseLinkLabel` 对未消费的 `[` 递归。0.5.1 已修了 wikilink rule 的同款问题,但 tag rule 漏改 —— 复现文件正是报告里的 `themen/Astronomie und Exobiologie.md`(`[[#Biomarker|…]]` 被表格 `|` 拆成 `[[#Biomarker`,其中 `#Biomarker` 命中 tag rule)。
+  - 修复:silent 模式下也把 `state.pos` 推过匹配长度再 `return true`,token 产出仍门控在 `!silent`(对齐 markdown-it 自带规则)。
+- **页内跳转锚点 `[[#heading]]` 即使 slug 精确匹配也被判死链 / 失去 `href`**(报告:仅德语主题就 74 处)。
+  - 根因:自引用 wikilink(只有 `#anchor`、无文件部分)解析时 `target` 被切成空串 → `lookupEntry('')`/`resolveSimple('')` 返回空 → 整条 wikilink 误判 dead。
+  - 修复:`core/resolver.ts` 与 `core/scan-wikilinks.ts` 双路径统一处理 —— 有 heading 部分且无文件部分时解析到**当前文件本身**,后续 heading 匹配(exact slug,各 `anchorMatch` 模式通吃)正常命中;`scan-wikilinks` 不再把自引用锚点计入死链汇总。
+- **缺失的 embed 资源(`![[foo.gif]]` / 音视频 / PDF 指向不存在文件)把整个 Vite/Rollup 构建硬中断**,报 `Rollup failed to resolve import "/foo.gif"`。
+  - 根因:`modules/embeds/image.ts` 与 `modules/embeds/media.ts` 在 asset 解析不到时回退成绝对路径 `/{basename}`,该 URL 被 VitePress 的 Vite 插件当模块 import,Rollup 解析不到即 throw。
+  - 修复:缺失资源不再产出会被 Vite 解析的 `src`,改为按 `deadLink` 策略告警(`silent`/`warn`/`error`,`error` 推 `index.warnings` 让构建以非零退出但不中断渲染)+ 渲染一个**不触发 Vite 解析**的占位 `<span class="ayn-embed ayn-embed--missing">`,与死链行为一致,绝不 throw。
+
+### Tests
+- 新增 `tests/v052-bugfixes.test.ts`(Bug1 silent-pos / Bug2 自引用锚点 + scanWikilinks / Bug3 image+media 缺失占位 + `deadLink='error'` 告警)。
+- 更新 `tests/render.test.ts`、`tests/v03-phase2.test.ts`:缺失 image/media 现在断言占位 `<span>` 而非旧的会崩 build 的 `<img>/<audio>/<iframe src="/…">`;media player 用例改指向 `fixtures/vault/media/` 下的真实占位资源。
+- 真实 `vitepress build` 端到端验证(复现 Astronomie 嵌套链接 + 自引用锚点 + 缺失 gif/mp4/pdf)全部通过:无 `state.pos` 崩溃、零死链上报、缺失 embed 降级告警、`build complete` 退出码 0。
+
+### Files touched
+- `src/modules/tags/rule.ts`(silent 推进 `state.pos`)
+- `src/core/resolver.ts`、`src/core/scan-wikilinks.ts`(自引用锚点 → 当前文件)
+- `src/modules/embeds/image.ts`、`src/modules/embeds/media.ts`(缺失资源 → 占位 + `deadLink` 策略,不 throw)
+
+## [0.5.1] - 2026-06-20
+
+### Fixed
+- **致命崩溃:wikilink 在 markdown link label / 嵌套方括号 / GFM 表格单元格里会让整个 `vitepress build`/`dev` 中止**,报错 `inline rule didn't increment state.pos`。
+  - 根因:wikilink 的 inline rule 在 **silent 模式**(markdown-it 的 `parseLinkLabel → skipToken` 会以 silent 模式逐个跑 inline rule 来扫描 `[...]` label)下直接 `return true` 而**没有推进 `state.pos`**,违反 markdown-it 契约(`parser_inline.skipToken` 在规则返回 true 但 pos 未前进时抛此错)。`[[` 的第一个 `[` 触发 link 核心规则的 label 扫描时即命中。
+  - 修复:silent 模式下也把 `state.pos` 推过闭合 `]]` 再返回 true(对齐 markdown-it 自带规则如 backtick 的做法:silent 也设 pos,仅把 token 产出门控在 `!silent`)。`![[embed]]` 同路径一并修复。
+  - 影响面:任何把 `[[...]]` 或 `![[...]]` 放进 markdown link label、嵌套 `[ ... ]`、或 GFM 表格单元格的文档,此前会整站构建失败;现在正常渲染。
+  - 新增 7 个回归测试锁定该行为。
+
 ## [0.5.0] - 2026-06-20
 
 0.5.0 正式版。收口此前 4 个 beta(主题底层化 + `@layer`),并叠加图谱体验、UI 健壮性与文档站重做。

package/README.md

@@ -4,9 +4,15 @@
 
 Forked from [`actuallysomecat/markdown-it-wikilinks-plus`](https://github.com/actuallysomecat/markdown-it-wikilinks-plus) (MIT) 并针对 VitePress 大幅重写。
 
-## 当前版本:0.5.0(2026-06-20)
+## 当前版本:0.5.2(2026-06-20)
 
-**主题集成大改 —— 目标:让第三方 VitePress 主题作者不需要知道本插件存在**
+**实战 build-blocker 修复**(详见 [CHANGELOG](./CHANGELOG.md#052---2026-06-20)):
+
+- `#tag` 出现在 link label / 嵌套方括号 / GFM 表格单元格时不再让 `vitepress build` 整站崩溃(`inline rule didn't increment state.pos`)。
+- 页内自引用锚点 `[[#heading]]` 不再被误判死链 —— slug 精确匹配现在正常生成可点击 `href`。
+- 缺失的 embed 资源(`![[foo.gif]]` / 音视频 / PDF)不再硬中断 Vite 构建,改为按 `deadLink` 策略告警 + 渲染占位标记。
+
+### 0.5.1:主题集成大改 —— 目标:让第三方 VitePress 主题作者不需要知道本插件存在
 
 ### CSS 自动让用户赢(`@layer`)
 

package/dist/index.cjs

@@ -680,13 +680,11 @@ function resolveWikilink(rawTarget, index, options, kind = "page", currentSource
   const wasFolderForm = /\/$/.test(target);
   if (wasFolderForm) target = target.replace(/\/+$/, "");
   target = stripMarkdownExt(target);
-  const entry = lookupEntry(
-    target,
-    index,
-    options,
-    currentSourcePath,
-    wasFolderForm
-  );
+  let selfEntry;
+  if (!target && headingPart && currentSourcePath) {
+    selfEntry = index.files.get(currentSourcePath);
+  }
+  const entry = selfEntry ?? lookupEntry(target, index, options, currentSourcePath, wasFolderForm);
   if (!entry) {
     return {
       url: buildDeadUrl(rawTarget, options),
@@ -1038,14 +1036,14 @@ function renderImageHtml(rawTarget, aliasParts, env) {
   const { altText, dim } = parseAltAndDim(aliasParts);
   const processedTarget = options.embeds.postProcessImageTarget(rawTarget);
   const { asset } = resolveAsset(processedTarget, index, options, env.currentPath);
-  let src;
-  if (asset) {
-    asset.referencedBy.add(env.currentPath ?? "<unknown>");
-    env.referencedAssets?.add(asset);
-    src = buildPlaceholderUrl(asset, options) + options.embeds.uriSuffix;
-  } else {
-    src = options.base + encodeURIComponent(basename(processedTarget)) + options.embeds.uriSuffix;
+  if (!asset) {
+    handleMissingAsset(env, processedTarget);
+    return renderMissingImageHtml(processedTarget, options);
   }
+  let src;
+  asset.referencedBy.add(env.currentPath ?? "<unknown>");
+  env.referencedAssets?.add(asset);
+  src = buildPlaceholderUrl(asset, options) + options.embeds.uriSuffix;
   const finalAlt = determineAlt(altText, processedTarget, options);
   const attrs = {
     src,
@@ -1068,6 +1066,24 @@ function renderImageHtml(rawTarget, aliasParts, env) {
   }
   return "<img " + Object.entries(attrs).map(([k, v]) => `${escapeAttrName(k)}="${escapeHtml(v)}"`).join(" ") + " />";
 }
+function handleMissingAsset(env, target) {
+  const { options } = env;
+  if (options.deadLink === "silent") return;
+  const msg = `vitepress-allyouneed: missing image embed ![[${target}]]` + (env.currentPath ? ` (in ${env.currentPath})` : "");
+  if (options.deadLink === "warn") {
+    console.warn(msg);
+    return;
+  }
+  env.index.warnings.push({
+    kind: "unknown",
+    message: msg,
+    affected: env.currentPath ? [env.currentPath] : []
+  });
+}
+function renderMissingImageHtml(target, _options) {
+  const bn = basename(target);
+  return `<span class="ayn-embed ayn-embed--missing" data-missing-src="${escapeHtml(bn)}" title="Missing image: ${escapeHtml(target)}">\u26A0 ${escapeHtml(bn)}</span>`;
+}
 function handleImageEmbed(state, rawTarget, aliasParts, env) {
   const html = renderImageHtml(rawTarget, aliasParts, env);
   const token = state.push("html_inline", "", 0);
@@ -1292,14 +1308,42 @@ function resolveSrc(rawTarget, env) {
     env.referencedAssets?.add(asset);
     return buildPlaceholderUrl(asset, options) + options.embeds.uriSuffix;
   }
-  return options.base + encodeURIComponent(basename(processedTarget)) + options.embeds.uriSuffix;
+  return null;
+}
+function handleMissingMedia(env, kind, rawTarget) {
+  const { options } = env;
+  const processedTarget = options.embeds.postProcessImageTarget(rawTarget);
+  if (options.deadLink === "silent") return;
+  const msg = `vitepress-allyouneed: missing ${kind} embed ![[${processedTarget}]]` + (env.currentPath ? ` (in ${env.currentPath})` : "");
+  if (options.deadLink === "warn") {
+    console.warn(msg);
+    return;
+  }
+  env.index.warnings.push({
+    kind: "unknown",
+    message: msg,
+    affected: env.currentPath ? [env.currentPath] : []
+  });
+}
+function renderMissingMediaHtml(rawTarget, env) {
+  const processedTarget = env.options.embeds.postProcessImageTarget(rawTarget);
+  const bn = basename(processedTarget);
+  return `<span class="ayn-embed ayn-embed--missing" data-missing-src="${escapeHtml(bn)}" title="Missing media: ${escapeHtml(processedTarget)}">\u26A0 ${escapeHtml(bn)}</span>`;
 }
 function renderAudioHtml(rawTarget, _aliasParts, env) {
   const src = resolveSrc(rawTarget, env);
+  if (src === null) {
+    handleMissingMedia(env, "audio", rawTarget);
+    return renderMissingMediaHtml(rawTarget, env);
+  }
   return `<audio class="ayn-embed ayn-embed--audio" controls preload="metadata" src="${escapeHtml(src)}">Your browser does not support the audio element.</audio>`;
 }
 function renderVideoHtml(rawTarget, aliasParts, env) {
   const src = resolveSrc(rawTarget, env);
+  if (src === null) {
+    handleMissingMedia(env, "video", rawTarget);
+    return renderMissingMediaHtml(rawTarget, env);
+  }
   const dim = parseAliasDim(aliasParts);
   const attrs = [
     `class="ayn-embed ayn-embed--video"`,
@@ -1313,6 +1357,10 @@ function renderVideoHtml(rawTarget, aliasParts, env) {
 }
 function renderPdfHtml(rawTarget, aliasParts, env) {
   const src = resolveSrc(rawTarget, env);
+  if (src === null) {
+    handleMissingMedia(env, "pdf", rawTarget);
+    return renderMissingMediaHtml(rawTarget, env);
+  }
   const dim = parseAliasDim(aliasParts);
   const width = dim.width !== void 0 ? `${dim.width}px` : "100%";
   const height = dim.height !== void 0 ? `${dim.height}px` : "600px";
@@ -1355,7 +1403,10 @@ function makeWikilinkRule(scope) {
     inner = src.slice(innerStart, closeIdx);
     if (inner.includes("\n")) return false;
     if (!inner.trim()) return false;
-    if (silent) return true;
+    if (silent) {
+      state.pos = closeIdx + 2;
+      return true;
+    }
     const env = state.env;
     if (!env || !env.index || !env.options) {
       return false;
@@ -2284,7 +2335,7 @@ function renderTemplate(v) {
 // src/core/views/generate-data.ts
 var import_node_fs6 = __toESM(require("fs"), 1);
 var import_node_path6 = __toESM(require("path"), 1);
-var PLUGIN_VERSION = true ? "0.5.0" : "0.0.0-dev";
+var PLUGIN_VERSION = true ? "0.5.2" : "0.0.0-dev";
 var WIKILINK_RE = /(!?)\[\[([^\]\n]+)\]\]/g;
 var DEFAULT_BODY_TAG_RE = /(?:^|[\s([{,;。,;])#([\p{L}_][\p{L}\p{N}_/-]*)/gu;
 function buildBodyTagRe(userPattern) {
@@ -2643,7 +2694,10 @@ function makeTagRule() {
     const m = pattern.exec(slice);
     if (!m) return false;
     const tag = m[1];
-    if (silent) return true;
+    if (silent) {
+      state.pos = start + m[0].length;
+      return true;
+    }
     if (!env.referencedTags) env.referencedTags = /* @__PURE__ */ new Set();
     env.referencedTags.add(tag);
     const tagsViewName = env.options?.views?.names?.tags ?? "tags";
@@ -3789,7 +3843,8 @@ function scanWikilinks(index, options) {
           if (isAsset) continue;
         }
       }
-      const found = resolveSimple(rawTarget, index, options, f.relativePath);
+      const isSelfAnchor = !rawTarget && !!headingPart;
+      const found = isSelfAnchor || resolveSimple(rawTarget, index, options, f.relativePath);
       if (!found) {
         dead.push({
           source: f.relativePath,
@@ -3799,7 +3854,7 @@ function scanWikilinks(index, options) {
         continue;
       }
       if (scanAmbig && headingPart) {
-        const targetEntry = resolveSimpleEntry(rawTarget, index, options, f.relativePath);
+        const targetEntry = isSelfAnchor ? f : resolveSimpleEntry(rawTarget, index, options, f.relativePath);
         if (!targetEntry) continue;
         const matches2 = findAmbiguousLeadingNumberMatches(targetEntry, headingPart);
         if (matches2.length > 1) {