vitepress-allyouneed 0.1.0 → 0.3.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/CHANGELOG.md +171 -0
  2. package/dist/index.cjs +2028 -16
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +5 -3
  5. package/dist/index.d.ts +5 -3
  6. package/dist/index.js +2028 -16
  7. package/dist/index.js.map +1 -1
  8. package/dist/markdown-it.cjs +697 -11
  9. package/dist/markdown-it.cjs.map +1 -1
  10. package/dist/markdown-it.d.cts +1 -1
  11. package/dist/markdown-it.d.ts +1 -1
  12. package/dist/markdown-it.js +697 -11
  13. package/dist/markdown-it.js.map +1 -1
  14. package/dist/theme/components/DocHeader.vue +356 -0
  15. package/dist/theme/components/Layout.vue +58 -0
  16. package/dist/theme/components/Tags.vue +157 -0
  17. package/dist/theme/components/VaultGraph.vue +317 -0
  18. package/dist/theme/components/VaultStats.vue +53 -0
  19. package/dist/theme/composables/useVaultData.cjs +73 -0
  20. package/dist/theme/composables/useVaultData.cjs.map +1 -0
  21. package/dist/theme/composables/useVaultData.d.cts +61 -0
  22. package/dist/theme/composables/useVaultData.d.ts +61 -0
  23. package/dist/theme/composables/useVaultData.js +48 -0
  24. package/dist/theme/composables/useVaultData.js.map +1 -0
  25. package/dist/theme/index.cjs +115 -0
  26. package/dist/theme/index.cjs.map +1 -0
  27. package/dist/theme/index.d.cts +64 -0
  28. package/dist/theme/index.d.ts +64 -0
  29. package/dist/theme/index.js +75 -0
  30. package/dist/theme/index.js.map +1 -0
  31. package/dist/theme/styles/callouts.css +220 -0
  32. package/dist/theme/styles/doc-header.css +247 -0
  33. package/dist/theme/styles/graph.css +79 -0
  34. package/dist/theme/styles/index.css +8 -0
  35. package/dist/theme/styles/shared.css +170 -0
  36. package/dist/theme/styles/stats.css +77 -0
  37. package/dist/theme/styles/tags.css +308 -0
  38. package/dist/{types-CapUIPbW.d.cts → types-Dz5cMyYS.d.cts} +165 -0
  39. package/dist/{types-CapUIPbW.d.ts → types-Dz5cMyYS.d.ts} +165 -0
  40. package/dist/vite.cjs +311 -6
  41. package/dist/vite.cjs.map +1 -1
  42. package/dist/vite.d.cts +1 -1
  43. package/dist/vite.d.ts +1 -1
  44. package/dist/vite.js +311 -6
  45. package/dist/vite.js.map +1 -1
  46. package/dist/vitepress.cjs +2028 -16
  47. package/dist/vitepress.cjs.map +1 -1
  48. package/dist/vitepress.d.cts +1 -1
  49. package/dist/vitepress.d.ts +1 -1
  50. package/dist/vitepress.js +2028 -16
  51. package/dist/vitepress.js.map +1 -1
  52. package/package.json +24 -5
  53. package/style.css +39 -23
package/CHANGELOG.md CHANGED
@@ -2,6 +2,177 @@
2
2
 
3
3
  本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/);版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
4
4
 
5
+ ## [0.3.0-beta.0] - Unreleased
6
+
7
+ v0.3 把"接管 Obsidian 仓库"从能跑变成好用。补齐了 13 种 callouts、Pandoc footnotes、`==高亮==`、`%%注释%%`、`^block-ref`、`![[audio|video|pdf]]` 媒体嵌入;sidebar 不再需要手写(三种 layout + nav 自动生成 + `_sidebar.md` 手动覆盖);文档顶部加了 banner-style `DocHeader`(cover/dates/tags/word-count);Perspectives 视图组挪到 nav 下拉,不再污染各 tab sidebar;补全 11 篇用户文档 + 完整 frontmatter 字段表。
8
+
9
+ ### Added — Obsidian 语法(6 个新模块)
10
+
11
+ - **Callouts**(13 种 + 别名)`> [!type]` / `[!type]+` 折叠开 / `[!type]-` 折叠关 / 嵌套 `> > [!info]`;别名 `hint→tip` / `check→success` / `error→danger` 等全套
12
+ - **Highlight** `==text==` → `<mark>`;内部 markdown 继续解析(`==**bold**==` 嵌套正常);**与数学公式共存**:rule 注册时优先排在 `math_inline` 之后,公式里的 `==` 不会被吃
13
+ - **Comments** `%%inline%%` 静默吃掉 / 独占 fence `%%\n...\n%%` 整段隐藏
14
+ - **Footnotes**(Pandoc 风格)`text[^1]` + `[^1]: text`,自增编号、同 id 共享、多反链(用 `↑` 字符,非 emoji,CSS 强制 monospace 避免字体 emoji 化)
15
+ - **Block-refs**(渲染层)末尾 `^block-id` 剥除并挂 `id="^block-id"` + `class="ayn-block-anchor"` 到上一个 `*_open` token;URL hash 跳转可用
16
+ - **媒体嵌入** `![[clip.mp3]]` → `<audio controls>` / `![[movie.mp4|640x360]]` → `<video controls>` / `![[doc.pdf|800x600]]` → `<iframe>`;复用 image 同款 asset pipeline,Vite resolveId/load 自动处理新扩展名
17
+
18
+ ### Added — Sidebar 自动生成全套
19
+
20
+ - **三种 layout**:`'tree'`(默认,嵌套)/ `'flat'`(顶层平铺)/ `'per-folder'`(每顶级目录独立 sidebar,VitePress 按 URL 切换)
21
+ - **`autoNav: true`** —— 顶级目录自动变 nav tabs,带 `activeMatch`,子页面也保持高亮;`homeNavText` 可改首项文字
22
+ - **`autoFolderIndex` 三模式**:`'off'`(零侵入)/ **`'top-level'`(默认)**(只为顶级目录生成 index)/ `'all'`(所有目录都生成);支持 `mode/exclude/stripNumericPrefix/template` 对象细控;sentinel 保护,不覆盖用户文件;用户后加同名 dirIndex 时自动清理旧生成
23
+ - **`groupLink` 三模式**:`'all'`(默认,所有有 dirIndex 的 group 可点)/ `'top-level'`(子组只展开/折叠)/ `'off'`(都不可点)
24
+ - **`groupOrder: string[]`** —— 顶级 group 顺序覆盖
25
+ - **`stripNumericPrefix`** —— 默认 true,自动剥 `01-foo.md` `02_bar.md` 数字前缀显示为 "Foo" "Bar"
26
+ - **`maxDepth: number`** —— 嵌套深度上限
27
+ - **`exclude: string[]`** —— glob 排除(`drafts/**` / `wip-*.md`)
28
+ - **`sortBy`** —— `'order-then-title'`(默认)/ `'title'` / `'mtime-desc'`
29
+ - **新增公开 API** `generateNav(index, options, autoOptions)` —— 单独从顶层目录生成 nav array
30
+
31
+ ### Added — frontmatter 字段(新增 6 个,扩展原有)
32
+
33
+ - `sidebarCollapsed: boolean` —— dirIndex 用,控制该 group 默认折叠
34
+ - `sidebarGroup: string` —— **虚拟 group**,把文件抽到跨目录的命名组(如 "Customization")
35
+ - `cover: string` —— DocHeader banner 背景图,触发 banner 模式
36
+ - `banner.x/y/blur/opacity/overlay/text` —— banner 样式微调(位置/模糊/透明度/暗化/文字色)
37
+ - `created` / `updated` —— DocHeader 显示日期,`updated` 缺省 fallback `page.lastUpdated`
38
+ - `cssclasses: string[]` —— 应用到 `<body>` 的额外 class(挂载/卸载守恒)
39
+
40
+ ### Added — `_sidebar.md` 手动覆盖
41
+
42
+ - 任何目录放 `_sidebar.md` 即整段覆盖该目录 sidebar
43
+ - 两种写法:**frontmatter `sidebar:` 数组**(VitePress 原生 shape)/ **Markdown 列表**(`- [[wikilink|text]]` / `- [text](url)` / `- 纯文字 group` / 缩进嵌套 / `+`-展开 `-`-折叠后缀)
44
+ - `[[wikilink]]` 走 wikilink 同款解析(basename / alias / 相对 _sidebar.md / 绝对)
45
+ - 文件本身不出现在 sidebar item;也不进 stats/graph/tags 视图(`_` 前缀过滤)
46
+ - 解析失败降级到自动生成
47
+
48
+ ### Added — DocHeader(banner-style 文档头)
49
+
50
+ - 220px-320px 自适应高度横幅,圆角 4px(贴 VitePress 风格)
51
+ - 三层结构:背景图层 + 渐变遮罩层 + 居中内容层(`flex-direction: column; justify-content: flex-end` 让内容贴底)
52
+ - 大字号自适应:`clamp(2rem, 4.5vw, 3.25rem)`,长标题用 `-webkit-line-clamp: 2 + text-wrap: balance` 两行内换行
53
+ - **Mode B**(无 cover):**字号自动增大** `clamp(2.25rem, 5.5vw, 3.75rem)` 补偿无 banner 视觉缺失;走主题色 + 扁平 tag pill
54
+ - 自动隐藏文档第一个 H1(避免和 banner 标题重复);`layout: home` 时整个 DocHeader 跳过(VitePress 自带 hero)
55
+ - meta 行:lucide-style inline SVG 图标(Clock/Calendar/Edit3)+ ` • ` 分隔
56
+ - 中英文字数 + 阅读时长自动算
57
+ - frontmatter 完整可控:`banner.x/y/blur/opacity/overlay/text`
58
+
59
+ ### Added — 视图条目位置可选
60
+
61
+ - 新 `views.injectInto: 'sidebar' | 'nav' | 'both' | 'off'`(默认 **`'nav'`**);老 `views.sidebar: 'auto'|false` 仍兼容(自动映射)
62
+ - `'nav'`:Perspectives 进 nav 下拉,sidebar 不被污染(per-folder 推荐)
63
+ - `'sidebar'`:老行为,每个 sidebar 末尾追加 Perspectives 组
64
+ - `'both'`:两边都加
65
+ - 无论哪种模式,`/_perspectives_/` URL 都有 fallback sidebar(避免空 sidebar)
66
+
67
+ ### Added — 工程化
68
+
69
+ - **启动时预扫所有 wikilink**,死链集中 `console.warn`,免去 dev-server 打开每页才看到死链;扫描时正确跳过 fenced + inline code(`scanWikilinks` + `stripCodeForScan`)
70
+ - **wikilink 解析器加 fallback**:含 `/` 找不到绝对路径时,fallback 到"相对当前 source 文件目录"(模仿 Obsidian);scan-wikilinks 同步对齐
71
+ - **dirIndex 优先级**:`<folder>.md` > `index.md` > `README.md`(大小写不敏感);例 `tour/tour.md` 作为 tour group 的 link target
72
+ - 空 frontmatter-only dirIndex:**不当 link**,**autoFolderIndex 不覆盖**,**但 frontmatter 仍生效**(可用作"配置载体")
73
+
74
+ ### Added — 例子站重构
75
+
76
+ - 4 个分区:**Home**(landing page,VitePress `layout: home` hero+features)/ **Guide**(11 篇用户文档,含 `docs/` + `advanced/` 子组)/ **Tour**(showcase,分版本 + `changelog/` 子组)/ **Test**(`header/` 9 个 banner 组合 + `wikilinks/` + `transclusion/` + `misc/` 边缘 case)
77
+ - 启用 `markdown: { math: true }` + 加 `markdown-it-mathjax3` devDep;`/test/misc/math` 演示 KaTeX 公式 + 高亮 + 数学组合
78
+ - `/test/misc/mermaid-diagram.md` 说明如何接 `vitepress-plugin-mermaid`
79
+ - `/test/misc/_sidebar.md` 真实演示 sidebar override
80
+
81
+ ### Added — 文档(11 篇)
82
+
83
+ 新增/扩展 `examples/obsidian-vault/guide/`:
84
+
85
+ - `overview.md` — 11 篇文档导航(分必读/参考/进阶三组)
86
+ - `docs/install.md` — 安装 + peer dep + 文件结构
87
+ - `docs/configure.md` — 全部顶层 + scan/assets/wikilinks/embeds/views/sidebarAuto/modules/themeConfig.allyouneed 全字段细列
88
+ - `docs/frontmatter.md` —— **30+ 字段一份表**:每个标来源(AYN/VP/Obs/theme)、类型、默认值、作用 + 4 个完整示例 + 优先级速查
89
+ - `docs/sidebar-auto.md` —— 完整 `sidebarAuto` 参数 + 4 种 recipe + 三种 layout 对比
90
+ - `docs/sidebar-override.md` —— `_sidebar.md` 规范(两种写法 / 缩进 / 后缀 / 路径解析 / 用例)
91
+ - `docs/doc-header.md` —— banner frontmatter + themeConfig.allyouneed.docHeader
92
+ - `docs/obsidian-syntax.md` —— wikilinks / embeds / callouts / 行内 + 模块开关
93
+ - `advanced/custom-theme.md` —— 主题覆盖三段论
94
+ - `advanced/sidebar-recipes.md` —— 4 种典型 sidebar 配方
95
+ - `advanced/theme-interop.md` —— 与第三方主题协作 + **完整 `--ayn-*` CSS 变量速查**(callouts 13 type × 3 token、stats/tags/graph、highlight、footnote 等)+ className 速查 + 后加载覆盖原理
96
+ - `advanced/obsidian-compat.md` —— Obsidian 兼容性矩阵(✅/⚠️/❌ 三表) + 推荐迁移流程 + 与 Obsidian Publish 对比
97
+
98
+ ### Changed
99
+
100
+ - **视觉重做**
101
+ - Callout 改 细边框 + **左侧 3px 伪元素色条** + 中性灰底(不再 type 染色);**title 强制 `--vp-c-text-1` + `!important`** 永远清晰,accent 只作用在左色条 + icon;13 type accent 用 Tailwind 风高对比色(slate/blue/emerald/violet/amber/red/rose/purple/cyan)作为 fallback,**不依赖不存在的 `--vp-c-default-1` / `--vp-c-purple-*` 等**;暗色模式独立色阶
102
+ - Tag pill 全局扁平化:4px 圆角、monospace、无边框、`var(--vp-c-bg-soft)` 底,DocHeader banner 内是白色半透明版本
103
+ - DocHeader banner 高度从 400 → 220-320 横幅形态,圆角 12 → 4px
104
+ - **行为变化**
105
+ - 死链 `<a class="wikilink--dead">` **不再输出 href**,点击不会跳转;CSS 加 `text-decoration: line-through; cursor: not-allowed; opacity: 0.85`
106
+ - `views.injectInto` 默认从 `'sidebar'` 改成 `'nav'`(老 `views.sidebar: 'auto'` 仍映射回 `'sidebar'`)
107
+ - Perspectives 不再出现在各 tab 的 sidebar 末尾(默认),而是 nav 下拉
108
+
109
+ ### Fixed
110
+
111
+ - per-folder layout 下,sidebar 顶级 group 是 single wrap,VitePress 渲染成不可折叠 section header(level-0,无 toggle)。改成**直接展开成 sibling items**,所有子组都是 level-0 可正常 toggle
112
+ - per-folder layout 下,根 sidebar 的目录入口(Guide/Tour/Test)如果该目录没 dirIndex 就不可点。改成 fallback 到子树第一个 page URL,**永远可点**
113
+ - 删掉 `.vp-doc .callout { padding: 0 }` 老覆盖(和新左色条 padding 冲突)
114
+ - footnote backref `↩`(被部分字体当 emoji)→ `↑`(普通箭头)+ CSS 强制 monospace 字体
115
+ - `#v0.3` 这种带 `.` 的 tag 解析失败(`.` 不在合法 tag 字符):文档示例改用 `#v03`,加说明
116
+ - 文档示例里大量 `[[../path]]` 相对路径死链 → 改成 basename 或绝对路径
117
+ - `injectViewsSidebar` 在 per-folder object 形态下漏配 `/_perspectives_/` key,导致视图 URL 下 sidebar 为空 → 补 fallback sidebar(Home + 所有 tab 入口 + Perspectives 组)
118
+ - `scanWikilinks` 错把 fenced/inline code 内的 `[[note]]` 当死链 → `stripCodeForScan` 预处理跳过
119
+ - callout type-scoped 规则覆盖 `.callout-title` color 导致**淡色文字看不清** → title 永远 `--vp-c-text-1 !important`,accent 只用色条/icon
120
+
121
+ ### Migration
122
+
123
+ 老用户从 v0.2 升级一般无破坏。两点注意:
124
+
125
+ 1. 默认 `views.injectInto: 'nav'`(老默认 `'sidebar'`)→ Perspectives 改在 nav 下拉。想退回老行为:`views: { injectInto: 'sidebar' }` 或老 `views: { sidebar: 'auto' }`
126
+ 2. 死链 `<a class="wikilink--dead">` 不再有 href;如果你 CSS 依赖 `[href]` 选择器要调
127
+
128
+ ### Test coverage
129
+
130
+ 新增 5 个测试文件,覆盖 80+ 新断言:
131
+
132
+ - `tests/callouts.test.ts` — 13 type + 别名 + 折叠 + 嵌套 + 模块开关(21 个)
133
+ - `tests/highlight-comments.test.ts` — 高亮 + 注释 + 模块开关(10 个)
134
+ - `tests/v03-phase2.test.ts` — media embed + footnotes + block-refs(18 个)
135
+ - `tests/sidebar-auto-v03.test.ts` — layout × 3 + dirIndex 优先级 + 空 dirIndex + sortBy + groupOrder + stripNumericPrefix + maxDepth + groupLink × 3 + sidebarGroup + generateNav(15+ 个)
136
+ - `tests/v03-extras.test.ts` — `_sidebar.md` parser + `generateFolderIndexes` 三模式 + `scanWikilinks` 跳 code + 相对路径 fallback + `views.injectInto` 四模式(14+ 个)
137
+
138
+ ### Added — Obsidian 语法
139
+
140
+ - **Callouts**(13 种 + 别名):`> [!note] / [!info] / [!tip] / [!success] / [!question] / [!warning] / [!failure] / [!danger] / [!bug] / [!example] / [!quote] / [!abstract] / [!todo]`。支持 `[!type]+` / `[!type]-` 折叠,支持自定义 title,支持嵌套(`> > [!info]`),body 内 markdown 继续解析。每种 type 内置 lucide-style SVG 图标和独立配色 CSS 变量(`--ayn-callout-<type>-{accent,bg,border}`)。
141
+ - **Highlight**:`==text==` → `<mark>`,内部 markdown 继续解析(`==**bold**==` 嵌套正常)。
142
+ - **Comments**:`%%inline%%` 静默吃掉;独占 fence 形式 `%% ... %%` 整段隐藏。
143
+ - **Footnotes**(Pandoc 风格):`text[^1]` + `[^1]: footnote text`。自增编号、同 id 共享编号 + 多反链 `↩`、文末追加 `<section class="ayn-footnotes">`。
144
+ - **Block refs**(渲染层):末尾 `^block-id` 剥除并挂 `id="^block-id"` + `class="ayn-block-anchor"` 到上一个 `*_open` token(浏览器原生 anchor scroll 即用;wikilink 路由 `[[note#^id]]` 留到 v0.4)。
145
+ - **Audio / Video / PDF embed**:`![[clip.mp3]]` → `<audio controls>`,`![[movie.mp4|640x360]]` → `<video controls width height>`,`![[doc.pdf|800x900]]` → `<iframe>`。复用现有 image 同款 asset pipeline,Vite resolveId/load 自动处理新扩展名。
146
+
147
+ ### Added — 工程化
148
+
149
+ - **Sidebar 自动生成** (`sidebarAuto`):从 vault 目录结构自动生成 VitePress sidebar。支持三种 mode:`'off'` / `'fill-if-empty'`(默认,只在用户没写时填) / `'force'`(总是覆盖)。
150
+ - 排序:`order-then-title`(默认,frontmatter.order 升序) / `'title'` / `'mtime-desc'`。
151
+ - frontmatter 三个 key 可自定义:`sidebarTitle`(覆盖标题)、`sidebarHidden: true`(隐藏)、`order`(排序权重)。
152
+ - `_` 前缀目录自动隐藏(Obsidian 私有/草稿约定)、视图 `_perspectives_/` 自动排除。
153
+ - 支持 `exclude: ['drafts/**']` 简单 glob。
154
+ - **DocHeader** Vue 组件:在 `doc-before` slot 注入文档头。
155
+ - cover 图(`frontmatter.cover` URL/path;或开启 `coverMode: 'gradient'` 走 tag-hash 着色兜底)
156
+ - 时间行(`frontmatter.created` + `frontmatter.updated` / fallback `page.lastUpdated`)
157
+ - tag pills(`frontmatter.tags`,点击跳到 `_perspectives_/tags#tag`)
158
+ - 字数 + 阅读时长(从 DOM 算,中英文分别计数)
159
+ - **自定义 Layout**:替换默认 `Theme.Layout`,在 `doc-before` 注入 DocHeader,同时把 `frontmatter.cssclasses` 应用到 `<body>` 上(挂载时加、卸载时清,跨页守恒)。
160
+ - **模块开关全量铺平**:`modules.{callouts, highlight, comments, footnotes, blockRefs, sidebarAuto}` 全部可独立开关,默认全开。
161
+
162
+ ### Changed
163
+
164
+ - 公共类型 `AllYouNeedOptions.modules` 新增 6 个键、`ResolvedOptions` 同步;新增 `AllYouNeedOptions.sidebarAuto`(`SidebarAutoUserOptions`)。
165
+ - `vitepress.ts` wrapper 在 `themeConfig.sidebar` 处理链上新增"sidebar 自动生成 → 视图条目注入"两步。
166
+
167
+ ### Notes
168
+
169
+ - v0.3.0 不动 v0.2 已稳的 vault scanner / asset pipeline / views(graph/stats/tags)/ wikilinks 等模块;新模块全部以独立目录加入,旧接口零 breaking change。
170
+ - DocHeader 用 frontmatter 数据,所以"零配置"前提是用户在 `.md` 里写了对应 frontmatter(`cover/created/updated/tags`)—— 没写的话整个 header 不渲染,不会显示空壳。
171
+
172
+ ### Test coverage
173
+
174
+ 新增 4 个测试文件(callouts / highlight-comments / v03-phase2 / sidebar-auto),覆盖 50+ 个新断言,与既有 v0.2 测试一起跑应全绿。
175
+
5
176
  ## [0.2.0] - Planned
6
177
 
7
178
  计划加的"插件自动生成视图":