MD (Markdown) 语法详细教程 obsidian 社区转载

这份资料在圈子里流传的版本不少，核心内容是一致的：一套围绕 Markdown 语法的系统讲解，来源是 Obsidian 社区的整理与转载。它不是那种只讲「星号加粗、井号标题」的入门贴，而是把语法拆到能直接往笔记库里落地的粒度。如果你已经在用 Obsidian，或者打算把零散笔记迁进一个本地优先的知识库，这份教程的价值在于它和 Obsidian 的渲染规则对得上——哪些写法在标准 CommonMark 里成立、哪些是 Obsidian 扩展的方言，边界讲得比较清楚。

技术栈定位：Markdown 是格式，不是工具

先说清楚它解决的是什么问题。Markdown 本身是一层轻量标记，用来把纯文本转成结构化内容。真正决定「怎么写才生效」的，是渲染器。同一段语法，在 GitHub、在静态站点生成器、在 Obsidian 里表现可能不一样。Obsidian 走的是 CommonMark 加自家扩展的路线，支持双链、嵌入、callout、属性区（frontmatter）、Mermaid 之类的块级结构。

所以这份教程的定位不是「教你一个软件怎么用」，而是「教你一套标记语言在 Obsidian 这个渲染环境里怎么用准」。这个区分很重要：语法是跨平台的，写法习惯是跟着工具走的。文档里涉及行内样式、列表嵌套、引用块、代码围栏、表格、链接与图片引用，也覆盖 Obsidian 特有的任务列表、内部链接、区块引用和嵌入语法。学完你能拿同一套写法喂给 Typora、VS Code 预览或静态博客，知道哪部分需要改。

资料结构与可复用部分

内容组织上按语法类别推进，基本是「写法示例 + 渲染效果说明」的对照路子。这种结构的好处在复习：你不需要通读，遇到具体场景回查对应段落就行——比如表格怎么对齐、代码块怎么标语言、嵌套列表缩进几个空格才不塌。这类细节看视频容易走神，看文本对照反而快。

能直接复用的部分有几块：

• 标题层级与段落换行的规则，涉及 Obsidian 里换行需不需要空行、硬换行的处理方式；
• 列表与任务列表的缩进写法，直接关系到嵌套复选框是否渲染正确；
• 代码块与行内代码的围栏语法，含语言标识对高亮的影响；
• 链接、图片与内部链接（wikilink）的两种写法差异，以及引用块嵌入的用法；
• 表格、分隔线、转义字符这些容易在导出时出问题的边缘语法。

这些写法可以直接抄进自己的模板库，比如日记模板、会议记录模板、读书笔记模板，改改字段就能用。

对 Obsidian 用户的额外意义

Obsidian 的知识库是纯文本存的，文件即数据。这意味着语法写得规整，后期迁移成本就低——换编辑器、上静态站点、做批量正则替换，都不会因为写法随意而炸掉。教程里对双链和嵌入的处理，正好落在「笔记怎么互相引用、怎么把一段内容嵌进另一篇」这个场景上，这是普通 Markdown 教程不讲的。

另一个绕不开的点是 frontmatter，也就是文件顶部那段属性区。Obsidian 的标签、别名、发布日期多在这里定义，写错位置或格式，整个属性块就失效。文档对这块有覆盖，适合拿来做自己的元数据规范。

怎么用这份资料

建议不要从头背语法。打开 Obsidian 建一个测试库，边看边敲，重点验证两件事：一是嵌套结构（列表套列表、引用套代码块）是否按预期渲染，二是同一写法在不同预览环境里表现是否一致。遇到渲染不符预期的地方，回文档对照找出差异，比记规则有用。

自学的路径可以这样排：先过一遍行内样式和标题段落，把基础排版稳定下来；再攻列表、代码块、表格这类块级结构，这部分决定笔记的可读性；最后集中处理链接、嵌入和 frontmatter，把笔记连成网。整个过程可以配着自己的真实笔记做，不要另建一堆无意义的测试文件——语法只有用在要留存的资料上，才记得住。

如果后续打算把库发布成静态站点，语法层能提前避掉很多转换坑。这也是这份资料值得对照实践的原因：它讲的不是孤立的符号，而是符号在具体工具链里的行为。