Last updated: Monday 07 September 2026 @ 20:44:27

mdbook-obsidian-format 操作手册

mdbook-obsidian-format 用于让 mdBook 正文直接使用 Obsidian 的 WikiLink 和 Embed 语法。

本地源码：/Users/ruoyangdong/project/rust/mdbook-obsidian-format

原仓库：https://github.com/Quaternijkon/mdbook-obsidian-format

转换只发生在 mdBook 构建时的内存 Book 中，不会改写原 Markdown 文件。

普通 WikiLink

样例

实际效果：[[Homepage]]

对应源码：

[[Homepage]]

没有扩展名时会自动按 Markdown 章节处理并补 .md。

WikiLink 别名

样例

实际效果：[[Homepage|返回首页]]

对应源码：

[[Homepage|返回首页]]

竖线右侧是页面上显示的文字。

指向子目录中的章节

样例

实际效果：[[Paper/ANNS/FlowANN]]

对应源码：

[[Paper/ANNS/FlowANN]]

所有路径都相对于 mdBook 的 src 根目录解析。

路径 + 别名

样例

实际效果：[[Paper/ANNS/FlowANN|FlowANN 论文笔记]]

对应源码：

[[Paper/ANNS/FlowANN|FlowANN 论文笔记]]

指向章节标题

[[Paper/ANNS/FlowANN#某个标题]]

也可以带别名：

[[Paper/ANNS/FlowANN#某个标题|跳到指定小节]]

构建后会变成带 heading anchor 的标准 Markdown 链接。

图片 Embed

![[assets/logo.png]]

图片会转换成标准 Markdown image。

PDF Embed

![[downloads/manual.pdf]]

当前实现会转换成普通文件链接，不会生成 PDF viewer。

音频 Embed

![[audio/intro.mp3]]

会转换成普通文件链接，不会自动生成播放器。

视频或其他非图片文件

![[video/demo.mp4]]

同样按普通文件链接处理。

笔记 Embed

![[Paper/ANNS/FlowANN]]

当前不会把另一个 Markdown 章节正文完整嵌入本页，而是降级为该笔记的普通链接。

目标不存在时

当前配置：

warn-on-missing = true

因此：

1. 构建输出 warning；
2. 仍生成链接；
3. 不会直接中止构建。

如不希望 warning：

[preprocessor.obsidian-format]
warn-on-missing = false

是否处理 Embed

当前：

transform-embeds = true

因此 ![[...]] 会转换。

若希望保留原始 Obsidian Embed 文本：

transform-embeds = false

不会转换的区域

下面这些区域会保持原样：

• YAML Frontmatter；
• fenced code block；
• 行内代码；
• raw HTML；
• callout；
• Obsidian properties；
• tags；
• comments；
• Dataview；
• Mermaid；
• MathJax / 数学公式。

为什么代码块里的 WikiLink 不会变化

例如：

```markdown
[[Homepage]]
```

因为 fenced code block 是示例源码，插件会跳过它。这正适合操作手册中展示 Obsidian 语法。

Block Anchor

Obsidian block reference 没有直接对应的 mdBook 标准能力，因此 block anchor 会降级为文件链接。

需要稳定页内定位时，优先使用 heading：

[[Note#Heading]]

SUMMARY.md 不能使用 WikiLink

SUMMARY.md 会在 preprocessor 运行前由 mdBook 自己解析，因此必须使用标准 Markdown link：

- [FlowANN](Paper/ANNS/FlowANN.md)

不能写：

- [[Paper/ANNS/FlowANN]]

正文页面则可以正常使用 WikiLink。

当前配置

[preprocessor.obsidian-format]
after = ["index", "frontmatter-render"]
warn-on-missing = true
transform-embeds = true

与 frontmatter-render 的配合

当前顺序：

frontmatter-render → obsidian-format → renderer

常用写法速查