双链使用指南

本站在 Obsidian 中编写，文件名用英文短横线（history.md），标题用中文（「历史与起源」）。网站构建时会把 [[双链]] 解析成普通链接，Markdown 源文件里仍保留 Obsidian 的原始写法，两边看到的链接一致。

支持的写法

写法	用途
[[历史与起源]]	用中文标题引用笔记
[[ESP32-S3]]	用标题或文件名引用，不区分大小写
[[小智 AI|小智]]	自定义显示文字（表格里要写成 |）
[[历史与起源#时间线]]	指向其他笔记里的某个标题
[[#支持的写法]]	指向本页标题
[[docs/chips/index|芯片型号]]	用仓库路径消除歧义

实际示例：关于本站、编写原则、下一节。

解析规则

网站按以下顺序寻找目标，找到唯一一篇就停止：

1. 仓库路径：docs/chips/esp32-s3 或 chips/esp32-s3。
2. 相对当前笔记的路径：同目录下的 [[index]] 指向本目录导读。
3. 文件名、title 和 aliases，比较时忽略大小写并统一 Unicode 规范形式。

找不到目标或命中多篇时，构建直接失败并指出文件，不会发布一个打不开的链接。遇到重名（例如各目录都有 index）时改用 docs/ 开头的完整路径。

为什么每篇都要写 aliases

Obsidian 只按文件名和 aliases 解析双链，不看 title。本站文件名是英文，所以每篇文章的 aliases 必须包含 title，Obsidian 里输入 [[历史与起源]] 才能跳转、补全和显示在关系图里。

内容检查会拦下缺少别名的文章。新建文章后在仓库根目录运行：

npm run docs:aliases

脚本只在 frontmatter 中补上 title，不改动其他字段。想让同一篇笔记多一个叫法（例如「小智」「xiaozhi」），直接追加到 aliases。

反向链接

文章底部的「引用本页的笔记」列出所有用 [[双链]] 指向本页的文章。标准 Markdown 链接 [文字](../chips/esp32.md) 也能正常跳转，但只算导航，不计入反向链接。想让两篇笔记在知识图谱里互相关联，用双链。

暂不支持

• ![[嵌入]]：图片请用标准 Markdown 语法 ![说明](../assets/xxx.png)。
• 块引用 [[笔记#^block-id]]：改用标题链接。
• Obsidian callout（> [!note]）：改用 VitePress 的 ::: tip、::: warning。

这些写法会让构建报错，而不是在网站上悄悄渲染成错误的样子。代码块和行内代码里的 [[...]] 不会被解析，可以放心写示例。

修改后记得重启

双链目标表在开发服务启动时读取一次。新增、重命名笔记或修改 aliases 后，重启 npm run docs:dev。