vitepress-allyouneed 0.3.8 → 0.4.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.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)。
+
+系统性优化 + 删除老 feature + 重构。**没有运行时崩坏的迁移成本**(老配置仍 typecheck 通过,运行时 warn;一个例外见下)。
+
+### Breaking
+- **`sidebarAuto.autoFolderIndex` 彻底删除**(整个 feature 不再存在 + 不再写文件)。这是唯一真正 breaking 的改动 —— 老配置中带 `autoFolderIndex` 字段 typecheck 仍过(字段类型为 `unknown`),运行时 console.warn 一次。**`generateFolderIndexes` / `FOLDER_INDEX_SENTINEL` 等导出已删,引用它们的代码会报错。**
+
+### Removed
+- **整个 `generate-folder-index.ts` 模块**(autoFolderIndex 实现)。文件夹 URL 现在由 `folderLinkOrder` 在 sidebar / nav / wikilink 解析时直接处理 —— 不再写 `index.md` 文件。之前生成过的 `index.md`(含 sentinel `<!-- generated by vitepress-allyouneed/folder-index -->`)留在原地,可手动删。
+
+### Added
+- **`sidebarAuto.folderLinkOrder: Array<'same-name' | 'index' | 'readme' | 'first-file'>`(默认 `['same-name', 'index', 'readme', 'first-file']`)**:文件夹链接解析顺序,**第一个命中的就用**。同时影响 sidebar group link、nav tab、`[[folder/]]` wikilink。
+  - 例:`['index']` 只用 `index.md`;`[]` = 文件夹永不可点;默认 = 全套兜底
+- **dev HMR 自动重启**:`.md` 文件 add/remove 或 `_sidebar.md` 内容编辑 → 自动触发 `server.restart()`,sidebar/nav 立刻反映。不再要求用户手动重启。
+- **leading-number 匹配放宽分隔符**:`#13` 现在匹配 `## 13) Optik`、`## 13: Foo`、`## 13, Bar`、`## 13 — Plain` 等。仍**不**匹 `## 13.5 Sub`(避免误匹版本号)。修 physik2 的 `Themenpool_Physik_Matura_2026#13-optik-und-wellenphaenomene` 跳不动 bug —— 现在匹中 `13) Optik und Wellenphänomene` 并用 heading 真实 slug `_13-optik-und-wellenphanomene`(VitePress @mdit-vue/shared 渲染出的 id)。
+
+### Deprecated(仍能用,v0.5 删)
+- **`sidebarAuto.folderLinkFallback`** → 用 `folderLinkOrder`。`'first-file'` ≡ 默认 order;`'none'` ≡ `[]`。同时设了的话 `folderLinkOrder` 优先。
+- **`sidebarAuto.layout: 'flat'`** → 用 `'tree'` 或 `'per-folder'`。运行时 console.warn 一次。
+- **`views.sidebar: 'auto' | false`** → 用 `views.injectInto: 'sidebar' | 'nav' | 'both' | 'off'`。运行时 console.warn 一次。
+
+### Internal refactor(无 API / 行为变化)
+- `humanize` / `compareEntries` / `titleForFile` / `buildStripPatternFromSeparators` 全部集中到 `src/core/sidebar-auto/internal.ts`,消除 3 套重复实现。
+- `DirNode` 不再有 `dirIndex` / `dirIndexEmpty` 单字段;改为 `dirIndexCandidates: Map<'same-name' | 'index' | 'readme', FileEntry>` + `resolveFolderLink(node, opts)` 运行时选 winner。
+- `pickDirIndexes` 重命名为 `pickDirIndexCandidates`。
+
+### DOCS
+- 删 autoFolderIndex 整段
+- 加 **"Sidebar × autoNav: combinations and what they do"** 章节(6 种 layout × autoNav 组合的运行逻辑 + 典型用例)
+- 加 **"Folder URLs (v0.3.10 — no more index file generation)"** 章节
+- `folderLinkOrder` 完整文档 + 示例
+- cheatsheet 全字段更新
+
+### Tests
+- `tests/v0310-folder-link-order.test.ts` 新增,15+ 用例覆盖 default / 自定义 order / 老 fallback 兼容 / nav / wikilink / autoFolderIndex 删除
+- 删 `tests/v03-extras.test.ts` 的 generateFolderIndexes 三模式 block
+- 删 `tests/v035-folder-link.test.ts` 的 F2 默认模板 block
+- 删 `tests/v034-bugfixes.test.ts` 的 Bug 2 块(autoFolderIndex 死链 — 不再相关)
+
+## [0.3.9] - 2026-05-21
+
+### Added
+- **`wikilinks.anchorMatch: 'exact' | 'leading-number' | 'fuzzy'`(默认 `'leading-number'`)**:三种锚点匹配模式。
+  - `'exact'` 严格,对齐 Obsidian
+  - `'leading-number'`(默认)按章节号前缀匹配:`[[X#7.2]]` 命中 `## 7.2 Antike — Vorsokratiker`
+  - `'fuzzy'`(实验性,99% 可用)leading-number + 全文 prefix + token 全词匹配
+- **`leading-number` 锚点歧义汇总告警**:scanWikilinks 启动时若发现 `#7.2` 同时匹配多个 heading,console.warn 列出所有候选 + 已选中的那个。
+- **`views.inlineTagPattern: RegExp`**:行内 `#tag` 正则可覆盖。
+- **`comments.preserveAsHtmlComment: boolean`(默认 `true`)**:`%%comment%%` 现在默认渲染为 `<!--comment-->`。**隐私警示**:别在 `%%` 里写敏感内容,view-source 看得见。
+- **`_sidebar.md` 内嵌 `{folder1, folder2}` 占位符**:markdown list 项末尾可写 `- Mechanics {Themen/Thema_08, Themen/Thema_11}`,自动展开两个文件夹的直接文件平铺在 group 下,子文件夹保留嵌套。支持 `,` / `，` / `、` 三种分隔符。手动写的子 items 附加在展开后面。
+  - **路径语义**:无 `/` 前缀 = 相对当前 `_sidebar.md` 所在文件夹;有 `/` 前缀 = srcDir 绝对路径(像 markdown 链接的习惯)
+  - **排序**:用 `sidebarAuto.sortBy`(默认 `order-then-title`)与主 sidebar 一致
+  - **过滤**:frontmatter `sidebarHidden: true` 的文件被跳过
+  - **折叠**:子目录 nested group 用 `sidebarAuto.collapsed`
+  - **顺序**:`sidebarAuto.foldersFirst` 控制子目录 vs 文件先后
+- **`sidebarAuto.stripNumericPrefixPattern: RegExp`(默认 `/^\d+[-_\s]+/`)**:剥前导数字的正则可配。想支持 `1) Foo` 用 `/^\d+[\)\-_\s]+/`。⚠ 不要加 `.`(会吃版本号)。
+- **`sidebarAuto.stripNumericPrefixSeparators: string`(默认 `'-_\\s'`)**:友好版分隔符字符集 — 不用懂正则。内部生成 `/^\d+[<chars>]+/`。若 Pattern 同时设了,Pattern 优先。
+- **`_sidebar.md` frontmatter `sidebarAuto: {...}` 覆盖**:per-folder 规则覆盖。该 `_sidebar.md` 的 `{folder}` 展开用合并后的配置;其它文件夹不受影响。识别 `sortBy` / `collapsed` / `stripNumericPrefix(Pattern/Separators)` / `foldersFirst` / `hiddenKey` / `titleKey` / `orderKey`。
+- **`{.}` placeholder**:`_sidebar.md` 里 `{.}` 表示"当前 `_sidebar.md` 所在文件夹"。配 materialize 默认模板用,manual `_sidebar.md` 也能用。
+- **空 text + placeholder = inline 展开**:`- {sub}`(text 为空)展开内容**直接替换该 item**,不当 group 包裹。`- Group Name {sub}`(有 text)按 group 包裹。
+- **`sidebarAuto.materialize: 'off' | 'top-level' | 'all'`(默认 `'off'`,opt-in)**:把 sidebar 配置物化成每文件夹一个 `_sidebar.md`,frontmatter 含可注释的 `sidebarAuto:` override,body 默认 `- {.}` 占位符,每次 build 重新展开 → 用户编辑(改名 / 加组 / 加项)后**仍自动适配新文件**。sentinel 保护,用户去掉 sentinel 后插件永不再动。
+- **VaultGraph 缩放联动 label**:像 Obsidian 一样,缩小到 0.9 以下 label 开始淡出,到 0.4 完全隐藏。
+- **`DOCS.md`**:完整配置参考,含每个字段类型 + 默认值 + 一个可复制粘贴的"全量默认配置" cheat sheet。
+
+### Fixed
+- **VaultGraph 点击节点导航**:`router.go(d.url)` 之前直接传 base-less URL,deploy 在 `/sub/` base 时路由错。改用 `withBase(d.url)`。
+- **Tags 视图文件链接同上**:`<a :href="f.url">` 改为 `withBase(f.url)`。
+
+### Changed
+- **所有内置文案 / console 消息以英语为基准**:transclusion 错误、dead link warn、视图生成日志、URL 冲突告警、DocHeader 日期(`May 21, 2026` 风格 en-US 格式化)、`Created` / `Updated` / `X min read` 等。debug 日志统一前缀 `[vitepress-allyouneed]` + 英文 message。
+- **`anchorMatch` 默认 `'leading-number'`**(不是 0.3.8 的 fuzzy 行为)。Obsidian 严格匹配用户设 `'exact'`;0.3.8 fuzzy 行为用户设 `'fuzzy'`。
+
+### Tests
+- 新增 `tests/v039-config.test.ts`,14 条用例覆盖 4 个特性。
+
+### Migration
+- physik2 / 章节号笔记用户:default 模式已自动覆盖你的 `#7.2 / #11.1 / ...` 写法,**无需配置**。
+- 0.3.8 fuzzy 重度依赖者:加 `wikilinks: { anchorMatch: 'fuzzy' }`。
+- 之前 `%%comment%%` 当"真隐藏"的用户:加 `comments: { preserveAsHtmlComment: false }`。
+
 ## [0.3.8] - 2026-05-21
 
 ### Fixed

package/README.md

@@ -4,6 +4,19 @@
 
 Forked from [`actuallysomecat/markdown-it-wikilinks-plus`](https://github.com/actuallysomecat/markdown-it-wikilinks-plus) (MIT) 并针对 VitePress 大幅重写。
 
+## 当前版本:0.4.1(2026-05-21)
+
+**0.4.x 重要变更(从 0.3.x 升级看这里)**
+
+- **`sidebarAuto.autoFolderIndex` 已删除**。文件夹链接由 `sidebarAuto.folderLinkOrder`(默认 `['same-name', 'index', 'readme', 'first-file']`)在 sidebar/nav/wikilink 解析时直接处理,不再生成 `index.md` 文件。配置里还留着这个字段会在控制台 warn 一次,删掉就行。
+- **`folderLinkOrder`** 新增 — 自定义文件夹链接来源顺序;`[]` 表示文件夹不可点。
+- **数字排序修正(0.4.1)**:`1, 2, 10, 11` 真按数字大小排,不再字典序成 `1, 10, 11, 2`。
+- **`markdown.math: true`** 自动检测 — 没装 `markdown-it-mathjax3` 时给清晰提示,一行 `npm i -D markdown-it-mathjax3` 即可。
+- **dev HMR**:`.md` add/remove 或 `_sidebar.md` 改动自动 server restart,sidebar 立即刷新。
+- **leading-number 锚点**:`#13` 现在能匹 `## 13) Optik`、`13: ...`、`13, ...`、`13 — ...`。不匹 `13.5 Sub`(避免吃版本号)。
+
+完整 changelog 见 [`CHANGELOG.md`](./CHANGELOG.md);配置参考见 [`DOCS.md`](./DOCS.md)。
+
 ## 这个包做什么
 
 - 让 VitePress 直接把你的 **Obsidian vault 当作 srcDir 用**,你照常写笔记,剩下交给插件:
@@ -79,7 +92,9 @@ export default defineConfig({
 
 ## 选项
 
-完整列表见 [`src/core/types.ts`](./src/core/types.ts) 的 `AllYouNeedOptions`。常用如下:
+📖 **完整配置参考 + 可复制 cheat sheet:[`DOCS.md`](./DOCS.md)** — 所有可配置项 + 默认值 + 一键复制全量默认配置。
+
+常用速览:
 
 | 选项 | 类型 | 默认 | 说明 |
 |---|---|---|---|