vitepress-allyouneed 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/);版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
+
+## [0.2.0] - Planned
+
+计划加的"插件自动生成视图":
+
+- **VaultGraph** — 全站关系图(节点 = 笔记,边 = wikilink/transclusion)
+- **VaultStats** — vault 统计仪表盘(总页数/标签数/链接数/最近修改 …)
+- **Tags** — 标签云图 + 标签 → 笔记列表
+- 上述视图都作为虚拟 .md 页面自动生成、自动注入 sidebar 底部,用户无需手动配置
+
+实现机制:`viteAllYouNeed` 通过 Vite 的 `resolveId`/`load` 在 `_views/*.md`
+路径上产生虚拟模块;markdown 内容 = 自动生成的引导文字 + 嵌入的 Vue 组件。
+
+## [0.1.0] - Unreleased
+
+首个公开版本。Forked from [actuallysomecat/markdown-it-wikilinks-plus](https://github.com/actuallysomecat/markdown-it-wikilinks-plus) 并针对 VitePress 大幅重写。
+
+### Added
+
+- **VaultIndex 共享数据库**:扫描 srcDir 一次,产出完整索引(`files` / `byBasename` / `byAlias` / `byUrl` / `headings` / `tags` / `backlinks` / `assets`),后续模块均从此索引取数。
+- **wikilinks 模块**:`[[Page]]` / `[[Page|alias]]` / `[[Page#heading]]` / `[[Page#heading|alias]]`。
+  - 三档同名冲突策略(`shortest` / `first` / `error`,默认 `shortest`)。
+  - frontmatter `aliases:` 自动注册并优先于 basename 匹配。
+  - 大小写不敏感默认开启,保证 Linux/macOS 表现一致。
+  - 死链三档(`silent` / `warn` / `error`)、半死链(锚点未匹配)单独标记。
+  - href 经 `encodeURI`,attr 经 HTML escape,Unicode/空格安全。
+- **embeds 模块(image)**:`![[image.png]]` 全套尺寸语法:`|N`、`|xN`、`|NxN`、`|alt`、`|alt|NxN`。输出 `width`/`height` 属性而非 inline `style`。
+- **embeds 模块(transclusion)**:`![[note]]` 把目标笔记正文内联;`![[note#heading]]` 内联指定 heading 区间;含循环检测、嵌套深度限制、按内容哈希缓存。
+- **自动资源管线**:
+  - dev 模式 Vite 中间件按 basename 流式响应,零拷贝。
+  - build 模式 `emitFile` 输出到 `dist/_assets/<hash>-name.ext`(默认带 hash);开 `preserveAssetPaths` 可改为 `/assets/name.ext` 原路径模式。
+- **双使用模式**:`defineConfigWithAllYouNeed` 零配置 wrapper + 手动接线(`./markdown-it` + `./vite`)。
+- **VitePress 配置桥接**:自动同步 `srcDir` / `base` / `cleanUrls` / `markdown.anchor.slugify`。
+- **锚点 slugifier**:用 `@mdit-vue/shared`,与 VitePress 默认行为 100% 一致;支持 `{#custom-id}` 语法。
+- **完整的扫描忽略规则**:默认忽略 `node_modules` / `.git` / `.obsidian` / `.vitepress` / `dist` 等;可选 `respectGitignore`。
+
+### Compared to upstream (markdown-it-wikilinks-plus)
+
+- **修复**:`[[Page#heading]]` 之前完全不处理,现在按 VitePress 同款 slugify 解析。
+- **修复**:`![[note]]` 之前被静默降级为普通 `<a>`,现在真做 transclusion。
+- **修复**:`![[x.png|300]]`(仅指定宽度)之前被误判为 alt,现在按 Obsidian 行为处理。
+- **修复**:image 输出从 inline `style` 改为 `width`/`height` 属性。
+- **修复**:href 现在做 URL 编码;`[[note.md]]` 自动剥 `.md`/`.markdown`。
+- **修复**:`silent` 模式现在按 markdown-it 约定返回 `true`。
+- **新增**:vault 扫描、aliases 解析、死链检测、自动资源管线 —— 这些是 VitePress 场景下"开箱即用"的必备能力。
+- **移除**:`absoluteBaseURL` / `relativeBaseURL` / `forceAllLinksAbsolute` / `uriSuffix`(由 ConfigBridge 从 VitePress 自动同步);`sanitize-filename` / `extend` / `proper-url-join` 依赖(自实现或不需要)。
+
+### Polish (v0.1 收尾)
+
+- **默认样式表**:`style.css`,导出为 `vitepress-allyouneed/style.css`,在主题 entry 里 `import` 即可启用。覆盖 wikilink、wikilink--dead、wikilink--unmatched-anchor、transclusion 各种状态、暗色模式适配。
+- **URL 冲突告警**:扫描期检测多文件路由到同一 URL(典型:`index.md` + `README.md`),通过 Vite logger 打 warn。
+- **`README.md` 视为 index**:与 VitePress 默认行为对齐 —— `README.md`/`index.md` 都路由到目录根。
+- **VitePress `srcExclude` 自动透传**:`defineConfigWithAllYouNeed` 会把 VitePress 的 `srcExclude` 合并进我们扫描器的 `scan.exclude`,避免误扫排除的文件。
+
+### Credits
+
+Original `markdown-it-wikilinks-plus` © 2025 somecat(MIT)。
+本项目在其代码结构与选项语义基础上重写,保留 MIT 协议。

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2025 somecat (https://github.com/actuallysomecat)
+Copyright (c) 2026 tangxiaoyi97 (https://github.com/tangxiaoyi97)
+
+Forked from https://github.com/actuallysomecat/markdown-it-wikilinks-plus
+and substantially rewritten for VitePress.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# vitepress-allyouneed
+
+> Obsidian / Notion → VitePress 发布所需的全套语法扩展。零配置、自动资源管线、系统化 vault 索引。
+
+Forked from [`actuallysomecat/markdown-it-wikilinks-plus`](https://github.com/actuallysomecat/markdown-it-wikilinks-plus) (MIT) 并针对 VitePress 大幅重写。
+
+## 这个包做什么
+
+- 让 VitePress 直接把你的 **Obsidian vault 当作 srcDir 用**,你照常写笔记,剩下交给插件:
+  - `[[wikilink]]` / `[[wikilink|alias]]` / `[[note#heading]]` / `[[note|alias]]`(支持 Obsidian "shortest path",中文文件名/标题)
+  - `![[image.png]]` / `![[image.png|300]]` / `![[image.png|alt|300x200]]`(图片自动找)
+  - `![[note]]` / `![[note#heading]]` 笔记 transclusion(整篇内联 / 章节切片)
+  - frontmatter `aliases:` 自动注册为可解析名
+  - 死链三档处理(silent / warn / error)
+- **资源管线自动化**:你不必把图片放在 `public/`。dev 时 Vite 中间件按 basename 流式响应;build 时自动 emit 到 `dist/_assets/<hash>-name.ext`。
+- **systematic vault index**:扫一遍 vault 建一份完整 `VaultIndex`(files / aliases / tags / headings / backlinks / assets),后续模块(callouts、tags、dataview、graph 等)从同一份索引取数。
+
+## 安装
+
+```bash
+npm install vitepress-allyouneed
+# 或
+pnpm add vitepress-allyouneed
+yarn add vitepress-allyouneed
+```
+
+## 用法 — 零配置(推荐)
+
+```ts
+// .vitepress/config.ts
+import { defineConfigWithAllYouNeed } from 'vitepress-allyouneed/vitepress'
+
+export default defineConfigWithAllYouNeed({
+  title: 'My Vault',
+  srcDir: '../my-obsidian-vault',  // 你的 Obsidian vault 目录
+  cleanUrls: true,
+  // ⚠️ VitePress 把 README.md 和 index.md 都路由到 '/',二者并存会让首页 404。
+  // 自动告警 + 建议:扫描时若发现冲突会在控制台 warn,推荐这里二选一排除:
+  // srcExclude: ['README.md'],
+}, {
+  onConflict: 'shortest',
+})
+```
+
+加默认样式(可选,但强烈推荐 —— 否则 wikilink 看起来和普通链接一样):
+
+```ts
+// .vitepress/theme/index.ts
+import DefaultTheme from 'vitepress/theme'
+import 'vitepress-allyouneed/style.css'
+
+export default DefaultTheme
+```
+
+完事 —— 直接 `vitepress dev`。
+
+## 用法 — 手动接线(高级)
+
+```ts
+import { defineConfig } from 'vitepress'
+import allYouNeedMarkdownIt from 'vitepress-allyouneed/markdown-it'
+import { viteAllYouNeed } from 'vitepress-allyouneed/vite'
+
+export default defineConfig({
+  vite: {
+    plugins: [viteAllYouNeed({ srcDir: '/path/to/vault' })],
+  },
+  markdown: {
+    config(md) {
+      md.use(allYouNeedMarkdownIt, { srcDir: '/path/to/vault' })
+      // ... 其它 md.use(...) 顺序由你掌控
+    },
+  },
+})
+```
+
+注意:手动模式下你要自己保证 `md.render(src, env)` 调用时 `env` 上有 `index` / `options`。
+零配置模式由 wrapper 自动注入。
+
+## 选项
+
+完整列表见 [`src/core/types.ts`](./src/core/types.ts) 的 `AllYouNeedOptions`。常用如下:
+
+| 选项 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `srcDir` | `string` | 跟 VitePress `srcDir` 走 | vault 根目录(绝对或相对) |
+| `base` | `string` | 跟 VitePress `base` 走 | 站点 base |
+| `cleanUrls` | `boolean` | 跟 VitePress `cleanUrls` 走 | URL 是否带 `.html` |
+| `caseSensitive` | `boolean` | `false` | wikilink/asset 解析是否大小写敏感 |
+| `deadLink` | `'silent' \| 'warn' \| 'error'` | `'warn'` | 死链处理 |
+| `onConflict` | `'shortest' \| 'first' \| 'error'` | `'shortest'` | 同名文件冲突策略 |
+| `onAliasConflict` | `'first' \| 'error'` | `'first'` | alias 冲突策略 |
+| `slugify` | `(text: string) => string` | `@mdit-vue/shared` | 锚点 slugifier,必须与 VitePress `markdown.anchor.slugify` 一致 |
+| `assets.preserveAssetPaths` | `boolean` | `false` | true 保留原 vault 路径(`/assets/foo.png`)、不哈希;false 走 `/_assets/<hash>-foo.png` |
+| `assets.outputDir` | `string` | `'_assets'` | build 输出 asset 的目录(在 base 之后) |
+| `wikilinks.linkText` | `'basename' \| 'fullPath' \| fn` | `'basename'` | 默认 label 来源 |
+| `wikilinks.allowLinkLabelFormatting` | `boolean` | `false` | label 是否走 inline markdown 解析(有递归风险,默认关) |
+| `embeds.imageFileExt` | `string[]` | 常见 9 种 | 视为图片的扩展名 |
+| `embeds.defaultAltText` | `boolean \| string` | `false` | 缺省 alt 策略 |
+| `embeds.transclusionMaxDepth` | `number` | `8` | transclusion 最大递归深度 |
+
+## 从 `markdown-it-wikilinks-plus` 迁移
+
+| 原选项 | 新位置 / 替代 |
+|---|---|
+| `pageLink.absoluteBaseURL` / `relativeBaseURL` / `forceAllLinksAbsolute` | 移除。由 VitePress `base` 自动决定 |
+| `pageLink.uriSuffix` | 移除。由 VitePress `cleanUrls` 自动决定 |
+| `pageLink.postProcessLinkTarget` / `postProcessLinkLabel` | `wikilinks.postProcessLinkTarget` / `postProcessLinkLabel` |
+| `pageLink.allowLinkLabelFormatting` | `wikilinks.allowLinkLabelFormatting`(默认改为 `false`) |
+| `pageLink.htmlAttributes` | `wikilinks.htmlAttributes` |
+| `imageEmbed.*` | `embeds.*`(语义大体不变) |
+| `imageEmbed.absoluteBaseURL` 等 | 移除 |
+
+如果你之前的项目就是 11ty / pure markdown-it,直接用 `vitepress-allyouneed/markdown-it` 入口也能跑(只是少了 vault 扫描带来的自动解析能力,需要你自己提供 env)。
+
+## 内部架构
+
+```
+src/
+├── core/
+│   ├── types.ts          ← 所有公共类型
+│   ├── vault/            ← VaultScanner(扫描 + 索引)
+│   ├── resolver.ts       ← [[target]] → URL
+│   ├── slugify.ts        ← 锚点 slug
+│   ├── config-bridge.ts  ← 解析用户配置
+│   └── asset-pipeline/   ← dev 中间件 + build emit
+├── modules/
+│   ├── wikilinks/        ← [[]] 解析与渲染
+│   └── embeds/           ← ![[]] image + transclusion
+├── index.ts              ← 默认入口(markdown-it 插件 + re-export)
+├── markdown-it.ts        ← 仅 markdown-it 入口
+├── vite.ts               ← Vite 插件入口
+└── vitepress.ts          ← VitePress wrapper 入口
+```
+
+后续模块(`callouts/` / `tags/` / `dataview/` / `graph/` 等)按相同接口接入。
+
+## 测试
+
+```bash
+npm test
+```
+
+会跑 `tests/` 下的 vitest 套件,覆盖 VaultScanner、Resolver、渲染、utils 等。
+
+## 致谢
+
+- [`actuallysomecat/markdown-it-wikilinks-plus`](https://github.com/actuallysomecat/markdown-it-wikilinks-plus) — 提供了配置面与基础解析模型。
+- [@mdit-vue/shared](https://github.com/mdit-vue/mdit-vue) — slugifier。
+- [gray-matter](https://github.com/jonschlinkert/gray-matter) — frontmatter 解析  
+- [picomatch](https://github.com/micromatch/picomatch) — glob  
+- 白青 技术支持
+- Opus 4.7
+
+## License
+
+MIT。见 [LICENSE](./LICENSE) —— 保留了 upstream 的版权声明。