一、为什么要学习 MarkdownMarkdown 的本质是一种纯文本标记语言它用 #、*、[]、 等简单符号来表达排版格式写作时双手不用离开键盘专注内容而非调整字号和行距。纯文本意味着任何编辑器都能打开永远不会因为软件升级而打不开文件。它可以轻松转换为 HTML、PDF、Word 等格式是技术写作的标准工具。GitHub 的 README 文件、各大技术博客、项目文档几乎全部使用 Markdown。VS Code、Obsidian、Notion、Typora、飞书等主流工具均原生支持。纯文本格式天然适配 Git 版本管理多人协作时 diff 和 merge 非常清晰。ChatGPT 和 Claude 等大语言模型也天然理解 Markdown 格式便于 AI 辅助写作。Jekyll、Hugo、Hexo、Astro 等静态网站生成器均以 Markdown 为核心。这些优势让 Markdown 成为现代知识工作者的必备技能。常见的 Markdown 流派包括 CommonMark标准化基础语法、GFMGitHub 增强版、Obsidian Markdown支持双向链接等扩展。本文以通用语法为主同时标注 Obsidian 的专属特性方便读者区分。二、标题语法用 # 号定义文档结构使用 1 到 6 个 # 号可以创建 H1 到 H6 六级标题。# 号后面必须跟一个空格否则不会生效。# 一级标题建议每篇笔记只用一次作为文档大标题。正文内容建议从 ## 二级标题开始让结构更清晰。标题末尾的 # 号会被忽略无需刻意对齐。在 Obsidian 中标题有三大特殊作用。第一大纲面板自动生成文档目录基于标题层级构建可点击的导航树。第二可以通过 [[笔记名#标题]] 精准链接到特定标题位置实现跨笔记的精确引用。第三鼠标悬停在标题左侧箭头处可以折叠或展开该标题下的内容块方便浏览长文档。三级标题是最常用的层级四级及以下用于更细致的分类。三、文本格式化行内样式标记Markdown 使用符号包裹文字来实现行内格式。粗体用两个星号或两个下划线包裹**粗体** 或 __粗体__斜体用一个星号或一个下划线包裹*斜体* 或 _斜体_粗斜体用三个星号包裹***粗斜体***。删除线用两个波浪线包裹~~删除线~~。高亮用两个等号包裹高亮但这是 Obsidian 的扩展语法在 GitHub 或 VS Code 中可能不生效。使用建议粗体用于强调关键词和术语斜体用于引用标题或外文词汇删除线用于标记废弃内容高亮用于临时标注重要信息。尽量保持格式统一不要混用星号和下划线。四、引用与 Callout 提示框普通引用使用大于号 连续多个 属于同一个引用块引用内部可以嵌套标题、列表、代码等任何 Markdown 语法。引用适合引用他人文字或标注补充说明。Obsidian 的 Callout 是在引用基础上增加了彩色提示框功能语法为 [!类型] 标题正文另起一行。常用类型包括 note笔记、warning警告、tip技巧、info信息、danger危险、success成功、example示例等。Callout 比普通引用更醒目适合重点提示、踩坑预警、操作指引等场景。例如笔记提示、警告删除文件不可恢复、技巧快捷键操作、信息说明、危险不可逆操作等都能用不同的 Callout 类型清晰区分。Callout 还支持折叠和嵌套详细用法可查阅 Obsidian 官方文档。五、列表无序、有序与任务清单无序列表使用 -、* 或 符号加空格三者等价建议统一使用 - 保持风格一致。子列表通过缩进Tab 键或两个空格表示层级可以无限嵌套。需要注意不同 Markdown 引擎对列表嵌套的间距要求不同Obsidian 要求子列表前无空行GitHub 则允许空行。混用 Tab 和空格会导致层级错乱建议统一用 Tab。有序列表使用数字加英文句点加空格数字不必连续Markdown 会自动递增。例如全部写 1. 也会渲染为 1、2、3、4 的序列非常方便调整顺序。任务清单是 Obsidian 中极其常用的功能语法为 - [ ] 未完成 和 - [x] 已完成。渲染后显示可点击的复选框点击即可切换状态。配合 Dataview 插件可以跨笔记汇总所有未完成任务生成全局待办视图。任务清单非常适合学习计划、项目管理、日常待办等场景。六、代码与代码块行内代码使用单个反引号包裹适合标注命令、函数名、变量、文件路径等简短代码片段例如 npm install、print()、git commit 等。多行代码使用三个反引号围栏并在开头的三个反引号后指定编程语言名称即可获得语法高亮。Obsidian 支持 Python、JavaScript、TypeScript、C、Java、Go、Rust、SQL、Bash、HTML、CSS、JSON、YAML 等五十多种语言。代码块内可以包含任意代码内容并保持缩进和格式完整。技术写作中代码块是必不可少的工具。七、表格用竖线和短横组织数据Markdown 表格使用竖线 | 分隔列使用短横线 --- 分隔表头和数据行。对齐方式通过冒号控制--- 左对齐:---: 居中对齐---: 右对齐。表格不需要列对齐但格式化后源码更清晰。Markdown 表格不支持合并单元格如果需要复杂表格可以在 Markdown 中直接嵌入 HTML 的 table 标签Obsidian 支持混用 HTML。推荐使用编辑器插件自动格式化表格提高编写效率。表格适合展示对比数据、参数列表、配置说明等结构化信息。八、链接、图片与 Obsidian 内部链接外部超链接语法为 [显示文字](URL)可以添加悬停标题 [文字](URL 标题)。图片嵌入语法为 与链接的区别是前面多了一个感叹号。Obsidian 支持在图片链接后加 | 宽度 控制尺寸例如  限制宽度为 300 像素或 |300x200 精确控制宽高。Obsidian 还支持直接粘贴截图图片自动复制到附件文件夹并支持从文件管理器拖放插入。Obsidian 最核心的特色是内部双向链接语法为 [[笔记名]]。它可以链接到另一篇笔记也可以链接到特定标题[[笔记名#标题]]还支持别名显示[[笔记名|显示别名]]。用感叹号加双括号![[笔记名]]可以嵌入另一篇笔记的完整内容。内部链接的核心价值在于双向链接当笔记 A 链接到笔记 B 时B 的反向链接面板会自动显示 A形成知识网络。图谱视图可视化展示笔记之间的关联输入 [[ 时自动补全已有笔记名重命名笔记时自动更新所有引用这些都是 Obsidian 区别于普通编辑器的杀手级功能。YAML Front Matter 是笔记顶部的元数据配置区块用三个短横线 --- 包裹包含 title标题、tags标签、aliases别名、created创建日期、status状态等字段。标签支持嵌套如 编程/Python别名允许其他笔记通过别名链接到本文。Templater 插件可自动填充创建日期状态可标记为草稿、进行中或已完成。Front Matter 让笔记具备可检索和可分类的结构化属性。九、分隔线、转义字符与其他常用语法分隔线使用三个或以上的 ---、*** 或 ___ 单独成行。需要注意区分文档最顶部的 Front Matter--- 包裹的元数据和正文中的分隔线Obsidian 会根据上下文自动识别。反斜杠 \ 可以取消特殊符号的 Markdown 语义例如 \*这不是斜体\* 显示为星号而非斜体\# 这不是标题 显示为 # 而非标题。需要转义的字符包括反斜杠、星号、下划线、井号、反引号、方括号、圆括号、花括号、波浪线、竖线、大于号、小于号等。其他常用语法包括脚注[^1] 在正文文末定义 [^1]: 脚注内容、HTML 嵌入如 u下划线/u、sup上标/sup、Emoji:smile:、:1:、:tada:以及注释% 开头的行在部分引擎中视为注释。这些语法虽然不是核心但在特定场景下非常实用。十、综合实战示例下面展示一篇符合 Obsidian 最佳实践的完整笔记包含 Front Matter、标题层级、格式化、表格、Callout、任务清单、引用和内部链接。笔记顶部是 YAML Front Matter包含标题、标签、创建日期和状态。正文以一级标题开头然后是二级章节。核心概念部分用粗体和 Obsidian 高亮突出关键术语用有序列表列举三大要素。常用框架部分用表格对比不同框架的语言和特点。学习建议使用 Callout tip 提示框突出显示。学习计划使用任务清单列出可勾选步骤。最后用引用和内部链接关联相关笔记。这篇笔记综合运用了本文介绍的大部分语法展现了 Markdown 在实际写作中的高效和清晰。十一、常见错误与解决方案初学者常犯的错误有七种。第一# 号后忘加空格。#标题 不会渲染必须写成 # 标题。第二列表缩进不一致。混用 Tab 和空格会导致层级错乱建议统一用 Tab 键。第三代码块语言名写错。如 pythoon 无法高亮必须写 python 等正确名称。第四表格分隔符少写。表头和数据之间必须有分隔行否则不会识别为表格。第五链接括号顺序颠倒。正确顺序是 [文字](url)不是 (文字)[url]。第六图片语法忘记感叹号。[图片](url) 会变成普通链接必须写成 。第七Front Matter 格式错误。Front Matter 必须是文档的第一行前面不能有任何空行或缩进。第八高亮 在 GitHub 或 VS Code 中不生效这是 Obsidian 专属语法如需跨平台兼容应避免使用。遇到问题时先检查符号是否配对、空格是否存在、缩进是否统一大部分问题都能快速定位。十二、学习资源与进阶建议推荐学习资源包括菜鸟教程的 Markdown 章节、Obsidian 官方帮助文档、Markdown Guide 网站以及 GitHub Docs 中的 GFM 规范。进阶方向可以学习 Obsidian 的 Dataview 插件数据查询、Templater 插件模板自动化、以及 Mermaid 流程图绘制Obsidian 原生支持。对于技术写作者可以结合 Git 进行版本管理和协作或使用 Hugo、VuePress 等静态网站生成器将 Markdown 笔记发布为个人博客。掌握 Markdown 的日常语法后你将彻底告别鼠标调格式的繁琐所有排版工作都可以通过键盘完成。写作效率的提升不仅是速度更是心流状态的保持——无需在内容创作和格式调整之间频繁切换注意力。这正是 Markdown 历经二十年仍然长盛不衰的根本原因。