vitepress-allyouneed 0.4.0 → 0.5.0-beta.3

package/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/);版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## [0.5.0-beta.3] - 2026-05-22
+
+### Fixed
+- **Tags 视图(可能也包括其它视图)整片失样**:0.5.0-beta.0/.1/.2 的 `@layer` 声明用了 `@import url('./x.css') layer(vitepress-allyouneed)` 这种"在 @import 子句上挂 layer"语法。CSS 标准支持,但 **Vite + postcss-import / lightningcss 不同链路对它支持参差**:某些组合下 `layer()` 子句被吞,resolve 后的规则**没进 layer**;另一些组合下规则进了 layer 但没正确链入 layer order,被埋在最底层 specificity 一概输掉。Tags chip 失去 pill 样式就是这个症状(`.ayn-tag-chip` 的 padding/border/radius/bg 全输给 user-agent + VP)。
+- **改法**:不再用 `@import ... layer()`。每个 .css 文件**自己头尾**包 `@layer vitepress-allyouneed { ... }`,这是浏览器原生 cascade layer 语法,不经过 bundler 黑盒,100% 可靠。`styles/index.css` 退回最朴素的 `@import './x.css'`。
+- 行为不变:7 个 .css 全 layered,主题作者 unlayered CSS 自动赢。
+
+### Files touched
+- `src/theme/styles/index.css`(去 layer() 子句)
+- `src/theme/styles/shared.css`、`stats.css`、`tags.css`、`graph.css`、`callouts.css`、`doc-header.css`(各自头尾包 @layer block)
+- `style.css`(同上)
+
+## [0.5.0-beta.2] - 2026-05-22
+
+更彻底的修法:把 DocHeader 的 banner title 改成 `<div role="heading" aria-level="1">`,把 doc-header.css 放回 @layer,所有 7 个 .css 终于统一 layered。
+
+### Changed
+- **DocHeader banner 元素 `<h1>` → `<div role="heading" aria-level="1">`**:`.vp-doc h1` 选择器不再匹配我们,@layer 内 layered CSS 不再被 VitePress 默认 unlayered 32px 字号覆盖。
+  - 视觉:无差(`.ayn-doc-banner-title` 字号/字重等都生效)
+  - 辅助技术:WAI-ARIA 标准,屏幕阅读器按 h1 念出,跟原生 `<h1>` 等同
+  - SEO:Google 早期声明 `role="heading" aria-level="1"` 跟 `<h1>` 等价对待
+  - 文档大纲算法:99% 工具支持;少数 reader-mode 工具可能少识别一个标题
+- **doc-header.css 放回 `@layer vitepress-allyouneed`**:0.5.0-beta.1 的"豁免"特例不再需要。**所有 7 个 .css 都 layered**,主题作者覆盖故事彻底干净
+- `styles/index.css` 不再 split "layered / unlayered",注释简化
+
+### Why
+0.5.0-beta.0 引入 @layer 后,banner title 是 `<h1>` 在 `.vp-doc` 内,VP 默认 `.vp-doc h1 { font-size: 32px }` 是 unlayered,我们 layered CSS 永远输 → banner title 字号塌缩。0.5.0-beta.1 临时方案:doc-header.css 不 layer。0.5.0-beta.2 釜底抽薪:banner 不用 `<h1>` 元素了,VP 选择器抓不到我们。
+
+## [0.5.0-beta.1] - 2026-05-22
+
+### Fixed
+- **DocHeader banner title 字号丢失**(0.5.0-beta.0 回归):banner title 是 `<h1>` 在 `.vp-doc` 内,VitePress 默认 `.vp-doc h1 { font-size: 32px }` 是 unlayered;0.5.0-beta.0 把 `doc-header.css` 包进 `@layer vitepress-allyouneed` 后,**layered 永远输 unlayered**,我们的 `clamp(2rem, 4.5vw, 3.25rem)` 大字号被 VP 32px 覆盖 → "大标题"看起来变小。
+- **修法**:`doc-header.css` 不再 layer。原则上"必须压过 VP unlayered defaults 的 CSS"不能 layer;"用户可覆盖的装饰"才 layer。文档 `styles/index.css` 顶部添加注释说明这条边界
+- 其它 6 个 CSS 文件继续 layer(它们的 selector 不跟 VP 默认强冲突)
+
+### Note for theme authors
+想覆盖 banner title:写 `.ayn-doc-banner-title { ... }` —— 跟 0.4.x 行为一致(unlayered 源顺序赢)。注意我们文件在 `defineTheme` import 时加载,你 CSS 必须在它之后 import 才赢。
+
+## [0.5.0-beta.0] - 2026-05-21
+
+主题集成大改 —— **目标:让 3rd-party VitePress 主题作者完全不需要知道本插件**。
+
+### Theme: CSS 用 `@layer` 包裹(底层化)
+- 全部 7 个 .css 文件通过 `styles/index.css` 用 `@import ... layer(vitepress-allyouneed)` 加载,所有规则进 `vitepress-allyouneed` cascade layer
+- **后果**:用户(或第三方主题)写的任何 unlayered CSS **自动赢**我们,无论 specificity 或 import 顺序。`.wikilink { color: red }` 真就 red,不用知道我们有个 `.wikilink`
+- 删除全部 3 处 `!important`(`callouts.css` callout-title 色、`shared.css` mark 内 mathjax bg、`tags.css` tag link 下划线 reset)—— 它们都不需要 `!important`,specificity 已够,且 `!important` 会在 layer 内反向打败用户 unlayered。删了用户 100% 能盖
+- 浏览器支持:`@layer` Chrome/Edge 99 / Firefox 97 / Safari 15.4+(2022 春)
+
+### Theme: 新 `defineTheme()` 工厂(替代之前的 `withAllYouNeed` 设想)
+- `vitepress-allyouneed/theme` 默认导出仍是开箱即用的 Theme 对象,**额外**导出 `defineTheme(userTheme?)` 工厂
+- 三种用户场景:
+  1. **零配置**:`export { default } from 'vitepress-allyouneed/theme'` — 一行完事(DefaultTheme + 我们组件 + 我们 CSS)
+  2. **自定义 Layout / 加自己组件**:`defineTheme({ Layout, enhanceApp })`
+  3. **嵌 3rd-party 主题**:`defineTheme({ extends: SomeAwesomeTheme })`
+- 内部:用户 `enhanceApp` 在我们之后跑 → 同名 `app.component()` 注册**自动赢**(Vue last-registration-wins);用户 `Layout`、`setup` 直接替换
+- 主题包作者的工作流跟有没有本插件**完全无关**:他们写正常 VitePress 主题,published,最终用户负责 `defineTheme({ extends: ... })` 一行接入
+
+### Theme: 可被替换的 Vue 组件清单(API 契约)
+| 组件名 | 干什么 | 用户怎么换 |
+|---|---|---|
+| `Layout` | DefaultTheme.Layout + 自动 `<DocHeader />` + `frontmatter.cssclasses` → body | `defineTheme({ Layout: MyLayout })` |
+| `DocHeader` | 文档头:banner / 标题 / 时间 / tags | `app.component('DocHeader', MyDocHeader)` |
+| `VaultGraph` | d3 力导向关系图 | 同上 |
+| `VaultStats` | 统计卡片 | 同上 |
+| `Tags` | 标签云 + 搜索 + 列表 | 同上 |
+
+### Composables(显式契约)
+`useVaultData()` 早已暴露;0.5.0 起明确这是"给写自己 UI 的人"的公共 API。
+
+### Docs
+- `src/theme/index.ts` 文件头三段示例覆盖三种场景
+- README "当前版本" 章节同步
+- DOCS.md 新增 "Theming" 章节(下个 beta 补全)
+
+### Why beta
+- @layer 在 Vite CSS pipeline 的实际行为没在我这边 prod build 跑过,需要真实项目验证
+- `defineTheme()` 是新 API,等用户回声再 stabilize
+- 老 0.4.x 用户 `import AllYouNeedTheme from 'vitepress-allyouneed/theme'` 仍兼容(default export 没变),只是多了 `defineTheme` 命名导出
+
+### Migration from 0.4.x
+**完全无 breaking** —— 老代码继续跑。新代码推荐用 `defineTheme()`,见 README。
+
+## [0.4.1] - 2026-05-21
+
+修 0.4.0 几个回归 + 小幅 UX 优化。
+
+### Fixed
+- **数字排序坑**:`1. Masse / 10. Energie / 11. Impuls / 2. Dichte / 3. ...` —— title 比较改成 `localeCompare(b, undefined, { numeric: true })`(natural sort)。现在 `1, 2, 3, ..., 10, 11` 按数值排,而不是字典序的 `1, 10, 11, 2, 3`。影响 `sidebarAuto.sortBy` 的 `'title'` 与 `'order-then-title'`(后者在 order 缺失时 fallback 到 title)。
+- **`autoFolderIndex` 警告刷屏**:dev 模式 `server.restart()` 会反复触发,加 module-level once-flag 只报一次;同时把 message 写得更可操作("delete this field from your .vitepress/config.ts")。
+
+### Added
+- **`markdown-it-mathjax3` 友好提示**:用户在 vitepress config 写 `markdown: { math: true }` 但没装 `markdown-it-mathjax3` 时,wrapper 自动报一条带安装命令的提示。包加为 optional peer dependency,装与不装都不阻塞。
+- **VaultGraph 视觉/性能**:节点默认无边框(更 Obsidian-like,hover/active 才描边)。大图(>200 节点)启用 `alphaDecay` 加速 + 每 N 帧才更新一次 DOM,显著降卡。500 节点可用,1000+ 建议拆 vault。
+
+### Docs
+- README 加 "当前版本 0.4.1" + 0.3.x → 0.4.x 升级速览。
+- DOCS.md 内 `v0.3.10` 提法统一改成 `v0.4.0`(autoFolderIndex 删除事件实际发布在 0.4.0)。
+
 ## [0.4.0] - 2026-05-21
 
 **0.x.0 = breaking-ish minor bump**(按 0.x SemVer 约定大改 → 二位号 bump)。

package/README.md

@@ -4,6 +4,65 @@
 
 Forked from [`actuallysomecat/markdown-it-wikilinks-plus`](https://github.com/actuallysomecat/markdown-it-wikilinks-plus) (MIT) 并针对 VitePress 大幅重写。
 
+## 当前版本:0.5.0-beta.0(2026-05-21)
+
+**主题集成大改 —— 目标:让第三方 VitePress 主题作者不需要知道本插件存在**
+
+### CSS 自动让用户赢(`@layer`)
+
+我们所有 CSS 包在 `@layer vitepress-allyouneed` 里。CSS 标准规则:**任何 unlayered CSS 永远赢 layered CSS**,无关顺序、specificity。所以:
+
+```css
+/* 第三方主题随便写,自动赢 */
+.wikilink { color: red; }
+.callout { border-radius: 12px; }
+```
+
+零知识负担。
+
+### Vue 组件:`defineTheme()` 工厂
+
+三种场景,递进式:
+
+```ts
+// 1. 零配置(默认主题 + 我们)
+export { default } from 'vitepress-allyouneed/theme'
+
+// 2. 自定义 Layout / 覆盖某个视图
+import { defineTheme } from 'vitepress-allyouneed/theme'
+import MyLayout from './MyLayout.vue'
+import MyVaultGraph from './MyVaultGraph.vue'
+export default defineTheme({
+  Layout: MyLayout,
+  enhanceApp({ app }) {
+    app.component('VaultGraph', MyVaultGraph)  // 同名注册自动覆盖
+  },
+})
+
+// 3. 嵌别人写的 VitePress 主题(主题包作者无需感知本插件)
+import { defineTheme } from 'vitepress-allyouneed/theme'
+import SomeTheme from 'some-vitepress-theme'
+export default defineTheme({ extends: SomeTheme })
+```
+
+可被替换的全局组件:`Layout` / `DocHeader` / `VaultGraph` / `VaultStats` / `Tags`。
+
+### 4.x 兼容
+
+老代码 `import theme from 'vitepress-allyouneed/theme'; export default theme` 继续跑,没有 breaking。
+
+---
+
+### 0.4.x 重要变更(从 0.3.x 升级看这里)
+
+- **`sidebarAuto.autoFolderIndex` 已删除**。文件夹链接由 `sidebarAuto.folderLinkOrder`(默认 `['same-name', 'index', 'readme', 'first-file']`)在 sidebar/nav/wikilink 解析时直接处理。
+- **数字排序修正(0.4.1)**:`1, 2, 10, 11` 真按数字大小排。
+- **`markdown.math: true`** 自动检测 — 没装 `markdown-it-mathjax3` 时给清晰提示。
+- **dev HMR**:`.md` add/remove 或 `_sidebar.md` 改动自动 server restart。
+- **leading-number 锚点**:`#13` 能匹 `## 13) Optik`、`13: ...` 等。
+
+完整 changelog 见 [`CHANGELOG.md`](./CHANGELOG.md);配置参考见 [`DOCS.md`](./DOCS.md)。
+
 ## 这个包做什么
 
 - 让 VitePress 直接把你的 **Obsidian vault 当作 srcDir 用**,你照常写笔记,剩下交给插件:

package/dist/index.cjs

@@ -2102,11 +2102,10 @@ var markdown_it_default = allYouNeedMarkdownIt;
 
 // src/vite.ts
 var import_node_fs7 = __toESM(require("fs"), 1);
-var import_node_path8 = __toESM(require("path"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
 
 // src/core/asset-pipeline/dev-middleware.ts
 var import_node_fs4 = __toESM(require("fs"), 1);
-var import_node_path5 = __toESM(require("path"), 1);
 function createDevMiddleware(index, options) {
   return (req, res, next) => {
     if (!req.url) return next();
@@ -2124,25 +2123,38 @@ function createDevMiddleware(index, options) {
     if (!/\.[a-zA-Z0-9]+$/.test(decoded)) return next();
     const relCandidate = decoded.replace(/^\/+/, "");
     let asset = index.assetsByRelativePath.get(relCandidate);
-    if (!asset) {
+    if (!asset && !relCandidate.includes("/")) {
       const bn = basename(decoded);
       const map = options.caseSensitive ? index.assetsByBasename : index.assetsByBasenameLower;
       const key = options.caseSensitive ? bn : bn.toLowerCase();
       const candidates = map.get(key);
-      if (candidates && candidates.length > 0) asset = candidates[0];
+      if (candidates && candidates.length > 0) {
+        asset = [...candidates].sort(
+          (a, b) => a.relativePath.length - b.relativePath.length
+        )[0];
+      }
     }
     if (!asset) return next();
-    let stat;
-    try {
-      stat = import_node_fs4.default.statSync(asset.absolutePath);
-    } catch {
-      return next();
+    const etag = `W/"${asset.size.toString(16)}-${Math.floor(asset.mtime).toString(16)}"`;
+    const lastModified = new Date(asset.mtime).toUTCString();
+    const ifNoneMatch = req.headers["if-none-match"];
+    const ifModifiedSince = req.headers["if-modified-since"];
+    if (ifNoneMatch === etag || ifModifiedSince && Date.parse(ifModifiedSince) >= Math.floor(asset.mtime)) {
+      res.statusCode = 304;
+      res.setHeader("ETag", etag);
+      res.setHeader("Last-Modified", lastModified);
+      return res.end();
     }
     res.statusCode = 200;
     res.setHeader("Content-Type", guessMime(asset.extension));
-    res.setHeader("Content-Length", String(stat.size));
+    res.setHeader("Content-Length", String(asset.size));
     res.setHeader("Cache-Control", "no-cache");
-    import_node_fs4.default.createReadStream(asset.absolutePath).on("error", () => next()).pipe(res);
+    res.setHeader("ETag", etag);
+    res.setHeader("Last-Modified", lastModified);
+    import_node_fs4.default.createReadStream(asset.absolutePath).on("error", () => {
+      if (!res.headersSent) next();
+      else res.destroy();
+    }).pipe(res);
   };
 }
 var MIME = {
@@ -2174,14 +2186,14 @@ function guessMime(ext) {
 
 // src/core/views/generate-md.ts
 var import_node_fs5 = __toESM(require("fs"), 1);
-var import_node_path6 = __toESM(require("path"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
 var VIEW_SENTINEL = "<!-- generated by vitepress-allyouneed (do not edit; will be regenerated) -->";
 function generateViewMarkdown(options, index) {
   const report = { written: [], skipped: [] };
   if (!options.modules.views) return report;
-  const srcDir = import_node_path6.default.resolve(options.srcDir);
+  const srcDir = import_node_path5.default.resolve(options.srcDir);
   const prefix = options.views.urlPrefix;
-  const viewDir = prefix ? import_node_path6.default.join(srcDir, prefix) : srcDir;
+  const viewDir = prefix ? import_node_path5.default.join(srcDir, prefix) : srcDir;
   if (prefix) {
     try {
       import_node_fs5.default.mkdirSync(viewDir, { recursive: true });
@@ -2190,7 +2202,7 @@ function generateViewMarkdown(options, index) {
   }
   const views = buildViewList(options);
   for (const v of views) {
-    const target = import_node_path6.default.join(viewDir, v.fileName);
+    const target = import_node_path5.default.join(viewDir, v.fileName);
     if (import_node_fs5.default.existsSync(target)) {
       let existing;
       try {
@@ -2271,8 +2283,8 @@ function renderTemplate(v) {
 
 // src/core/views/generate-data.ts
 var import_node_fs6 = __toESM(require("fs"), 1);
-var import_node_path7 = __toESM(require("path"), 1);
-var PLUGIN_VERSION = "0.2.0-beta.0";
+var import_node_path6 = __toESM(require("path"), 1);
+var PLUGIN_VERSION = true ? "0.5.0-beta.3" : "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) {
@@ -2329,19 +2341,6 @@ function buildVaultData(index, options) {
   const edges = [...edgeMap.values()];
   const bodyTagRe = buildBodyTagRe(options.views.inlineTagPattern);
   const tagsMap = /* @__PURE__ */ new Map();
-  for (const f of userFiles) {
-    const allTags = new Set(f.tags);
-    if (options.views.parseInlineTags) {
-      for (const tm of f.content.matchAll(bodyTagRe)) {
-        allTags.add(tm[1]);
-      }
-    }
-    for (const tag of allTags) {
-      const arr = tagsMap.get(tag) ?? [];
-      arr.push(f);
-      tagsMap.set(tag, arr);
-    }
-  }
   const allTagsByFile = /* @__PURE__ */ new Map();
   for (const f of userFiles) {
     const set = new Set(f.tags);
@@ -2349,6 +2348,11 @@ function buildVaultData(index, options) {
       for (const tm of f.content.matchAll(bodyTagRe)) set.add(tm[1]);
     }
     allTagsByFile.set(f.relativePath, [...set]);
+    for (const tag of set) {
+      const arr = tagsMap.get(tag) ?? [];
+      arr.push(f);
+      tagsMap.set(tag, arr);
+    }
   }
   const tags = {};
   for (const [tag, files] of tagsMap) {
@@ -2391,9 +2395,9 @@ function buildVaultData(index, options) {
 function writeVaultData(index, options) {
   const data = buildVaultData(index, options);
   const json = JSON.stringify(data);
-  const publicDir = import_node_path7.default.join(import_node_path7.default.resolve(options.srcDir), "public");
+  const publicDir = import_node_path6.default.join(import_node_path6.default.resolve(options.srcDir), "public");
   import_node_fs6.default.mkdirSync(publicDir, { recursive: true });
-  const out = import_node_path7.default.join(publicDir, options.views.dataFileName);
+  const out = import_node_path6.default.join(publicDir, options.views.dataFileName);
   import_node_fs6.default.writeFileSync(out, json, "utf8");
   return { path: out, bytes: json.length };
 }
@@ -2458,7 +2462,7 @@ function viteAllYouNeed(userOptions = {}) {
     config(_userViteConfig, _envCtx) {
       const srcDirOpt = userOptions.srcDir;
       if (!srcDirOpt) return void 0;
-      const abs = toPosix(import_node_path8.default.resolve(srcDirOpt));
+      const abs = toPosix(import_node_path7.default.resolve(srcDirOpt));
       return {
         server: {
           fs: {
@@ -2540,9 +2544,15 @@ function viteAllYouNeed(userOptions = {}) {
           removeFile(index, ctx.file, resolved);
           if (wasIndexed) structuralChange = "remove";
         }
-      } catch {
-        removeFile(index, ctx.file, resolved);
-        if (wasIndexed) structuralChange = "remove";
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          removeFile(index, ctx.file, resolved);
+          if (wasIndexed) structuralChange = "remove";
+        } else {
+          console.warn(
+            `vitepress-allyouneed: stat failed for ${ctx.file} (${err.code ?? "unknown"}); keeping existing index entry.`
+          );
+        }
       }
       const baseName = ctx.file.split(/[\\/]/).pop() ?? "";
       const isSidebarFile = /^_sidebar\.(md|markdown)$/i.test(baseName);
@@ -3520,8 +3530,9 @@ function stripBase(url, base) {
   return "/" + url.slice(b.length);
 }
 function compareEntries(a, b, opts) {
+  const collateOpts = { numeric: true, sensitivity: "base" };
   if (opts.sortBy === "title") {
-    return opts.formatItemTitle(a).localeCompare(opts.formatItemTitle(b));
+    return opts.formatItemTitle(a).localeCompare(opts.formatItemTitle(b), void 0, collateOpts);
   }
   if (opts.sortBy === "mtime-desc") {
     return b.mtime - a.mtime;
@@ -3529,7 +3540,7 @@ function compareEntries(a, b, opts) {
   const oa = readOrder(a, opts.orderKey);
   const ob = readOrder(b, opts.orderKey);
   if (oa !== ob) return oa - ob;
-  return opts.formatItemTitle(a).localeCompare(opts.formatItemTitle(b));
+  return opts.formatItemTitle(a).localeCompare(opts.formatItemTitle(b), void 0, collateOpts);
 }
 function readOrder(entry, key) {
   const v = entry.frontmatter[key];
@@ -3593,7 +3604,7 @@ function computeGroupText(dir, dirIndex, opts) {
 
 // src/core/sidebar-auto/generate-sidebar-materialize.ts
 var import_node_fs8 = __toESM(require("fs"), 1);
-var import_node_path9 = __toESM(require("path"), 1);
+var import_node_path8 = __toESM(require("path"), 1);
 var SIDEBAR_MATERIALIZE_SENTINEL = "<!-- generated by vitepress-allyouneed/sidebar-materialize (do not edit if you want auto-refresh; remove this comment to take ownership) -->";
 var MD_RE = /\.(md|markdown)$/i;
 var SIDEBAR_RE = /^_sidebar\.(md|markdown)$/i;
@@ -3601,12 +3612,12 @@ function generateSidebarMaterializations(options, matOpts = {}) {
   const report = { written: [], skipped: [] };
   const mode = matOpts.mode ?? "off";
   if (mode === "off") return report;
-  const srcDir = import_node_path9.default.resolve(options.srcDir);
+  const srcDir = import_node_path8.default.resolve(options.srcDir);
   const viewsPrefix = options.views.urlPrefix ? options.views.urlPrefix.replace(/^\/+|\/+$/g, "") : "";
   const exclude = matOpts.exclude ?? [];
   const dirs = [srcDir, ...collectDirs(srcDir, srcDir, viewsPrefix, exclude, mode)];
   for (const dirAbs of dirs) {
-    const target = import_node_path9.default.join(dirAbs, "_sidebar.md");
+    const target = import_node_path8.default.join(dirAbs, "_sidebar.md");
     if (import_node_fs8.default.existsSync(target)) {
       let content;
       try {
@@ -3679,8 +3690,8 @@ function collectDirs(root, cur, viewsPrefix, exclude, mode) {
       if (!e.isDirectory()) continue;
       if (e.name.startsWith(".") || e.name.startsWith("_")) continue;
       if (e.name === "node_modules" || e.name === "public") continue;
-      const full = import_node_path9.default.join(dir, e.name);
-      const rel = import_node_path9.default.relative(root, full).split(import_node_path9.default.sep).join("/");
+      const full = import_node_path8.default.join(dir, e.name);
+      const rel = import_node_path8.default.relative(root, full).split(import_node_path8.default.sep).join("/");
       if (viewsPrefix && (rel === viewsPrefix || rel.startsWith(viewsPrefix + "/"))) continue;
       if (exclude.some((pat) => matchGlob(rel, pat))) continue;
       out.push(full);
@@ -3694,7 +3705,7 @@ function hasAnyMd(dir) {
     for (const e of entries) {
       if (e.isFile() && MD_RE.test(e.name) && !SIDEBAR_RE.test(e.name)) return true;
       if (e.isDirectory() && !e.name.startsWith("_") && !e.name.startsWith(".")) {
-        if (hasAnyMd(import_node_path9.default.join(dir, e.name))) return true;
+        if (hasAnyMd(import_node_path8.default.join(dir, e.name))) return true;
       }
     }
   } catch {
@@ -3712,9 +3723,47 @@ var WIKILINK_RE3 = /(!?)\[\[([^\]\n]+)\]\]/g;
 function stripCodeForScan(src) {
   let r = src.replace(/```[\s\S]*?```/g, (m) => " ".repeat(m.length));
   r = r.replace(/~~~[\s\S]*?~~~/g, (m) => " ".repeat(m.length));
-  r = r.replace(/(`+)(?:(?!\1)[\s\S])*?\1/g, (m) => " ".repeat(m.length));
+  r = stripInlineCodeLinear(r);
   return r;
 }
+function stripInlineCodeLinear(src) {
+  const out = src.split("");
+  let i = 0;
+  const n = src.length;
+  while (i < n) {
+    if (src.charCodeAt(i) !== 96) {
+      i += 1;
+      continue;
+    }
+    let openLen = 0;
+    while (i + openLen < n && src.charCodeAt(i + openLen) === 96) openLen += 1;
+    const contentStart = i + openLen;
+    let j = contentStart;
+    let closeAt = -1;
+    while (j < n) {
+      if (src.charCodeAt(j) === 96) {
+        let runLen = 0;
+        while (j + runLen < n && src.charCodeAt(j + runLen) === 96) runLen += 1;
+        if (runLen === openLen) {
+          closeAt = j;
+          break;
+        }
+        j += runLen;
+      } else {
+        j += 1;
+      }
+    }
+    if (closeAt === -1) {
+      i = contentStart;
+      continue;
+    }
+    for (let k = i; k < closeAt + openLen; k++) {
+      if (out[k] !== "\n") out[k] = " ";
+    }
+    i = closeAt + openLen;
+  }
+  return out.join("");
+}
 function scanWikilinks(index, options) {
   const dead = [];
   const ambiguous = [];
@@ -3864,6 +3913,23 @@ function resolveSimple(raw, index, options, currentSourceRel) {
 }
 
 // src/vitepress.ts
+var autoFolderIndexWarned = false;
+var mathHintShown = false;
+async function maybeHintMathPackage(config) {
+  if (mathHintShown) return;
+  const md = config.markdown;
+  const wantsMath = md?.math === true || md?.math !== null && !Array.isArray(md?.math) && typeof md?.math === "object";
+  if (!wantsMath) return;
+  mathHintShown = true;
+  const modName = "markdown-it-mathjax3";
+  try {
+    await import(modName);
+  } catch {
+    console.warn(
+      "[vitepress-allyouneed] `markdown.math: true` set but `markdown-it-mathjax3` is missing.\n  Install it once:  npm i -D markdown-it-mathjax3\n  (then no further setup \u2014 VitePress + this plugin will pick it up automatically.)"
+    );
+  }
+}
 function defineConfigWithAllYouNeed(config, pluginOptions = {}) {
   const vpExclude = Array.isArray(config.srcExclude) ? config.srcExclude : [];
   const mergedOptions = {
@@ -3879,6 +3945,7 @@ function defineConfigWithAllYouNeed(config, pluginOptions = {}) {
       ]
     }
   };
+  void maybeHintMathPackage(config);
   const vitePlugin = viteAllYouNeed(mergedOptions);
   const existingVite = typeof config.vite === "object" && config.vite !== null ? config.vite : {};
   const existingPlugins = Array.isArray(existingVite.plugins) ? existingVite.plugins : [];
@@ -3915,9 +3982,10 @@ function defineConfigWithAllYouNeed(config, pluginOptions = {}) {
     const shouldFill = sidebarMode === "force" || !userProvided;
     if (shouldFill) {
       try {
-        if (sidebarAuto.autoFolderIndex !== void 0) {
+        if (sidebarAuto.autoFolderIndex !== void 0 && !autoFolderIndexWarned) {
+          autoFolderIndexWarned = true;
           console.warn(
-            "vitepress-allyouneed: `sidebarAuto.autoFolderIndex` was removed in v0.3.10. Folder URLs are now resolved via `folderLinkOrder` (default: same-name \u2192 index \u2192 README \u2192 first-file). Previously generated index.md files (with our sentinel) are safe to delete manually."
+            "[vitepress-allyouneed] `sidebarAuto.autoFolderIndex` was removed in v0.4.0. No-op now \u2014 please delete this field from your .vitepress/config.ts. Folder URLs are resolved via `folderLinkOrder` (default: same-name \u2192 index \u2192 README \u2192 first-file). Old index.md files with our sentinel can be deleted by hand."
           );
         }
         const materializeMode = sidebarAuto.materialize ?? "off";