Obsidian 方言的 Markdown：语法清单与易错点

Obsidian 使用所谓 Obsidian Flavored Markdown（OFM，Obsidian 方言）：以 CommonMark 和 GitHub Flavored Markdown 为基础，再加一组自家扩展语法。理解哪些是标准语法、哪些是方言，能帮你避免「在 Obsidian 里好好的，粘到别处就乱了」的尴尬，也能让迁移过来的笔记更快融入。本章是一份带易错点注释的实用清单。

方言扩展语法总览

先看 Obsidian 在标准 Markdown 之上加了什么：

这些方言中，双链、注释、高亮在其他多数编辑器里会显示为纯文本；反过来说，标准 Markdown 语法在 Obsidian 全部可用。

基础格式速记

段落之间用空行分隔；单换行默认仍算同一段落，想要段内换行可以在行尾加两个空格，或直接按 Shift+Enter。标题用 # 到 ###### 六级。强调类语法如下：

**加粗**  *斜体*  ~~删除线~~  ==高亮==  `行内代码`

两个易错点值得单独提醒：

1. 中文与星号之间的空格。**加粗**中文 这种紧贴中文字符的写法，个别渲染场景可能解析失败，保险起见让符号两侧留空或保持标点分隔。
2. 转义。想原样显示 *、#、|、~ 等符号，在前面加反斜杠 \，例如 \*不是斜体\*。

双链与嵌入：方言的核心

[[笔记名]] 是最常用的方言语法，补充四种变体：

[[目标笔记]]                    <!-- 基本链接 -->
[[目标笔记|显示别名]]            <!-- 自定义显示文字 -->
[[目标笔记#某标题]]              <!-- 链接到指定标题（锚点） -->
[[2026-10-01#^abc123]]          <!-- 链接到块标识符为 abc123 的块 -->
![[图片.png|300]]               <!-- 嵌入图片并指定宽度 -->

文件名里应避免 # | ^ : %% [[ ]] 这些字符——它们在链接语法里有特殊含义，混用会导致链接失效。

Callout 提示块

Callout 是引用块的方言增强，第一行用 > [!类型] 标题 声明：

> [!warning] 注意
> 这是警告内容，支持 **Markdown** 和 [[内部链接]]。

常用类型有 note、info、tip、success、question、warning、danger、example、quote 等，类型标识大小写不敏感；写一个不认识的类型会回退为 note 样式。在类型后加 - 可默认折叠、加 + 默认展开，比如 > [!faq]- 折叠的问题。

注释与脚注

%%注释%% 只在编辑视图可见，阅读视图完全隐藏，适合给自己留批注或暂时停用的段落。注意：块注释以行首 %% 开始、%% 结束，忘了闭合会导致阅读视图把后面全部内容隐藏，这是新手高频事故。

脚注沿用常见扩展写法：

这句话需要一个出处[^1]。

[^1]: 出处在笔记末尾，支持多行内容。

表格、代码块与数学公式

表格用竖线分隔，表头行必须至少两个短横线；在 Live Preview 里右键表格可以直接增删行列、排序。表格单元格里要用双链别名或调整图片尺寸时，竖线需要写成 \| 转义。

代码块用三个反引号围起，首行标注语言可获得语法高亮（基于 Prism）。嵌套代码块时外层用四个以上反引号。数学公式用 $...$ 行内、$$...$$ 独立块，由 MathJax 渲染。

易错点汇总表

关于最后一条多说一句：如果笔记要频繁导出到不支持 Wikilink 的平台，进入 设置 → Files and links，关掉 Use [[Wikilinks]]，Obsidian 会改用 [显示文字](文件名.md) 的标准写法生成链接，互通性大增。

编辑视图的小知识

Obsidian 有两种编辑模式：Live Preview（默认，光标所在行显示原始语法，其余行即时渲染）和 Source mode（完全显示源码）。另有 Reading view 纯阅读模式，Ctrl+E（macOS 为 Cmd+E）在编辑与阅读之间切换。写模板或调 YAML 属性时建议临时切到 Source mode，避免 Live Preview 的属性面板干扰。

把这份清单当成速查表用即可，不必背。真正的熟练来自日常书写中遇到问题翻一次、修一次。下一章我们进入本书的主角——双链。

编辑效率快捷键

语法之外，编辑效率的大头在快捷键。系统级和框架级的快捷键无法在 Obsidian 内自定义，但值得全部记住：

几个组合技值得练成肌肉记忆：光标停在段落内不选文字，Ctrl+C 直接复制整段、Ctrl+X 剪切整段——移动段落的利器。列表里用 Tab / Shift+Tab 缩进与反缩进，比手动敲空格可靠得多。多光标（按住 Alt 点击多处）适合批量修改重复结构，虽然官方文档把它列为进阶功能，但值得十分钟学习。

从其他 Markdown 方言迁移的兼容提示

如果你的旧笔记来自 Typora、GitHub、语雀导出或其他方言环境，绝大多数格式会无缝工作，需要留意的差异点集中在几处：

• 内部链接：其他平台的相对路径链接（./notes/xxx.md）在 Obsidian 里大多能解析，但断链风险存在；迁移后用搜索抽查。
• %%注释%%：Obsidian 专属，其他平台显示为原文。反之，其他平台的 <!-- --> HTML 注释在 Obsidian 里同样有效，跨平台笔记建议用 HTML 注释。
• 任务列表扩展：- [x] 是通用写法，但「用任意字符标记完成」的特性是 Obsidian 的宽容度，别依赖。
• 代码块内语法：各平台高亮器不同，不影响内容本身。
• 表格对齐标记：:-- / :--: / --: 是 GFM 标准，通用。

一个实用的验证习惯：从旧平台迁入的第一周，随手翻几篇旧笔记的阅读视图，看到渲染异常就记下模式——通常同源笔记的问题是一致的，修一个模式等于修一批。

语法学习的最小路径

最后给一条高效学习路径，避免在语法细节里打转：第一周只需要掌握标题、加粗、列表、双链、代码块五样——它们覆盖日常书写的九成场景；第二周补上表格、Callout、任务列表；属性（YAML）和块引用等到需要结构化时再学。Obsidian 的好处是语法错了也不会「坏」——只是显示成原文，随时可改。这种低风险环境正是练语法最好的地方。

延伸阅读：Markdown 是纯文本力量的一个切面，文本处理的另一个必备技能是正则表达式，推荐 正则表达式从入门到精通；配合命令行工具的文本哲学，可延伸阅读 Claude Code 完全指南。

本章由 WorkBuddy 原创整理，功能行为依据 Obsidian 官方帮助文档。