被人问过无数次“Markdown基本语法难不难”，我的回答一直是：不难，但你得先搞清楚它到底在解决什么问题。Markdown是一种轻量级标记语言，用极简的符号代替Word里的各种排版按钮，让写作者把注意力放在内容本身。不管你是写博客、记笔记、写接口文档，还是在GitHub上维护README，Markdown都是那个最通用的文本格式。这篇内容适合完全零基础的新手，也适合用过一段时间但老在换行、表格、复制粘贴上翻车的朋友，我会把高频语法、编辑器配置和真实踩坑经历一次讲清。文章不搞“教科书式”罗列，而是按真实写作顺序，从标题到表格再到工具，尽量让你看完就能直接用。
1. 先搞懂Markdown是什么，再谈语法
1.1 Markdown不是编程语言，却比很多编程语言更常用
Markdown本质上是一个纯文本格式，你看到的一个后缀为.md或.markdown的文件，用任何文本编辑器打开，里面都是普通字符和少量符号。它不是编程语言，不需要编译，更不存在“运行环境”的问题。它的核心作用是用#、*、>、-这类标记，让纯文本在渲染后变成带层级、带强调、带列表的排版内容。
很多人第一次接触Markdown是在GitHub上，打开项目的README文件，发现页面里漂亮的标题和代码块，原来只是一份文本文件。这就是Markdown最有魅力的地方：同一份文件，在记事本里是可读的纯文本，在任意Markdown渲染器里是排版好的文档。它天然适合版本管理，Git能逐行比较差异；它也天然跨平台，换电脑换系统，文件内容不锁死在某个软件里。
所以你会发现，现代工具链几乎都在拥抱Markdown：博客系统支持它、笔记软件支持它、文档平台支持它，甚至给AI大模型准备提示词时，用Markdown也能让结构更清晰。与其说Markdown是一种语法，不如说它已经成为“通用写作格式”的默认答案。
1.2 学语法前必须先决定的编辑器方向
很多人一上来就背语法表，结果写了几遍还是记不住。我建议你先选一个编辑器，边写边看效果，让“符号”和“样式”之间形成条件反射。市面上的Markdown编辑器大体分三类：第一类是即时渲染型，代表是Typora、Obsidian阅读模式、语雀文档，你输入## 标题，回车后符号被隐藏，直接显示成标题样式；第二类是分屏预览型，代表是VS Code的Markdown Preview、Haroopad，左边写源码，右边看效果；第三类是纯源码编辑，比如记事本、Vim，适合快速改动，不适合新手学习。
我的建议很简单：新手优先用Typora或Obsidian，先看见结果再理解原理。程序员朋友可以直接用VS Code，配合插件就能获得极佳体验。无论选哪款，Markdown语法是通用的，编辑器只是辅助。别因为某个软件长得好看就觉得语法不同，真正跟着规范写，换编辑器几乎零成本迁移。
2. Markdown核心语法：标题、段落、换行、强调、列表、引用
2.1 标题语法与“标题消失”的真相
标题是Markdown里最常用也最容易出问题的语法。语法本身很简单：在行首加#号，一个#是一级标题，两个##是二级标题，最多支持六级标题。关键细节是#后面必须跟一个空格再写文字，否则在某些渲染器里不会识别成标题。
# 一级标题 ## 二级标题 ### 三级标题 ###### 六级标题很多朋友遇到过“修改标题之后没有#号了”的情况，我先给结论：绝大多数时候不是标题没了，而是所见即所得编辑器把#号隐藏了。在Typora这类即时渲染软件里，你把光标从标题行移开，#号会被藏起来，视觉上只剩加粗文字，但切到源码模式后#依然在。Obsidian的阅读视图也一样，想在编辑时看到#，需要切到编辑模式而不是阅读模式。VS Code不存在这个问题，因为预览窗口和源码窗口本来就是分开的。
另外还有一个隐蔽的坑：如果你在某个软件里发现“标题下面多了一条横线”，很可能不是分隔线，而是你在标题文字下方直接写了一行---，这个组合在不少渲染器里会被识别成“二级标题”而不是分隔线。后面讲分隔线时还会再提。
2.2 段落和换行：一个回车带来的困惑
“Markdown换行不生效”大概是新手第二大困惑。在Word里按回车就换行，但在Markdown里，普通回车只是把源码中的两段文字连接起来，渲染后大多数情况是一个空格。想要真正“换行”，有两种标准写法：一是在行尾输入两个空格再回车，二是用HTML标签<br>。
这是第一行（行尾有两个空格） 这是第二行 这是新段落，因为上面空了一行。如果你的需求是“另起一段”，最简单的方法是在两个句子之间空一行。很多平台会自动把连续的两个换行识别为段落结束，而单个换行会被忽略。比如在GitHub的Issue里，你写四行文字，每行之间只有单个换行，最终会显示成一段；如果你想列表项内部换行，也需要在行尾留两个空格，否则列表项会被截断。
我的习惯是：能空一行分段就空行，不依赖单换行。这样无论换到Typora、Obsidian还是VS Code，渲染效果都稳定。<br>虽然好用，但有些严格要求纯Markdown的环境会把它当作HTML过滤掉，所以尽量少用。
2.3 加粗、斜体与删除线：别把符号堆在一起
强调语法是日常写作的高频操作。用一组双星号包裹文字是加粗，一组单星号或单下划线是斜体，两组波浪线是删除线：
**这是加粗** *这是斜体* _这也是斜体_ ~~这是删除线~~注意星号与文字之间不能有空格，比如** 加粗 **在一些渲染器里不会生效。如果组合使用，比如同时加粗和斜体，可以写***内容***。这个写法容易和普通星号混淆，我建议新手记住“两组星号=粗体，一组星号=斜体”，需要组合时直接在外层加粗、内层斜体想象。
还有一个经常踩的坑：你写乘法3*4，结果“3”和“4”都变成了斜体或消失。解决办法是给星号加反斜杠转义，写成3\*4。删除线目前不是所有Markdown标准都支持，GitHub、Typora、Obsidian没问题，但某些极简渲染器可能不识别，如果你要发布到未知平台，最好提前测试。
2.4 有序列表、无序列表与嵌套列表：写目录和大纲的利器
列表是Markdown里“性价比”最高的语法。无序列表用-、*或+加空格开头，有序列表用1.加空格开头。嵌套列表则是在子项前面增加缩进，通常用两个或四个空格：
- 无序项一 - 无序项二 - 嵌套子项 - 嵌套子项 1. 第一步 2. 第二步 1. 子步骤一 2. 子步骤二有些编辑器允许你只写1.，后面的数字自动递增，但我还是建议手动写全数字，因为在某些平台或复制场景下自动编号可能失效。嵌套列表的缩进宽容度因渲染器而异，VS Code和GitHub要求严格，Typora可以自动调整。如果发现子项没有缩进效果，多半是“子项前少了空格”或者上一级列表后没有正确换行。
列表还可以和任务列表混排，下一部分会单独讲。写长文时，我习惯先用无序列表搭提纲，再逐个改成正文段落，这样文档结构从一开始就是清晰的。
2.5 引用块和分隔线：让文章更有层次
引用块用于标注他人的话、重要提示或长文引言，语法是在每行行首加>：
> 这是一段引用。 > > 引用中的第二段，中间空一行。 > 可以嵌套的引用 >> 二级引用引用块里的内容同样可以使用加粗、斜体、链接甚至代码块。很多教程只告诉你用一个>，但实际写作中“空一行再引用”“引用内分段”更常用。遇到多个>嵌套时要注意，嵌套太深容易让排版混乱，一般不超过两层。
分隔线则是用三个以上连续的-、*或_独占一行：
---但它有个大坑：如果分隔线的上方没有空行，而且上方恰好是一行文字，这行文字会被变成“二级标题”。所以写分隔线时，我永远会在前面空一行。这也能解释很多人“为什么我的正文突然变大变粗了”的原因。
3. 进阶语法实操：链接、图片、表格、代码块、公式
3.1 链接和图片：一张图讲明白的区别
行内链接的语法是[链接文字](网址)，支持相对路径，也支持锚点跳转。比如在本地仓库里写[安装文档](./docs/install.md)，点击就能打开同级的docs文件夹下的文档。图片的语法只比链接多一个英文感叹号：。这个“替代文字”千万不要省略，图片加载失败时，读者至少能看到说明；屏幕阅读器也会朗读它。
[打开百度](https://www.baidu.com) 如果想把图片变成可点击链接，可以把整张图片放进链接语法里：[](跳转地址)。引用式链接适合同一个链接在文中出现多次的情况：在文中写[文字][id]，在文末单独定义[id]: https://example.com，方便统一维护。
图片最大的坑是“本地图片只能在本地预览，传到博客后失效”。我现在写文档都建议把图片放在项目内的images目录，用相对路径引用；如果发到线上，提前把图片上传到图床，再把图片地址换成绝对URL。
3.2 表格语法：从入门到复制粘贴不翻车
Markdown表格是一种妥协式的表格实现，靠管道符|和短横线-拼出来。语法分三部分：表头、分隔行、表体。分隔行里用冒号控制对齐方式。
| 姓名 | 年龄 | 城市 | | :--- | :---: | ---: | | 张三 | 25 | 北京 | | 李四 | 30 | 上海 |第三行:---表示左对齐，:---:表示居中，---:表示右对齐。表格里的内容如果包含竖线|，需要转义成\|，否则表格会被截断。在代码块里展示管道符时也要注意，如果你用单反引号包围一段带有|的内容，一般没问题；但如果你想专门讲“表格怎么写”，通常要用双反引号包裹整个示例，或者把代码块语言标记为text。
表格的另一个痛点是“复制粘贴”。直接复制预览区表格到微信、Word或Excel，经常变成一坨混乱的纯文本。原因在于这些软件不识别Markdown表格语法，粘贴的是渲染后的HTML或纯文本。解决思路我在第5部分详细讲，但这里先给个提醒：别在表格里塞大段文字，一旦某个单元格内容过多，预览和导出都会变得很难看。
3.3 行内代码与独立代码块：代码高亮的关键
写技术文档，代码相关语法几乎绕不开。单个反引号包裹的是行内代码，比如npm install。连续三个反引号并指定语言类型，可以生成带有语法高亮的独立代码块：
行内代码：赶紧运行 `npm install` ```javascript const a = 1; console.log(a);注意上面这段是Markdown源码的示意写法，真正使用时，开头的三个反引号后面紧跟着语言名，比如`javascript`、`python`、`bash`、`json`。核心价值是让渲染器识别语言并高亮关键字。不写语言名也能生成代码块，只是没有高亮，在很多平台上不美观。 如果代码本身包含反引号，比如行内代码是markdown符号，你可以用双反引号包裹，例如`` 这里可以写一个反引号 ` ``。这个技巧不常用，但遇到“Markdown里展示Markdown”时特别有用。代码块里的内容几乎是“原样输出”的，Markdown语法不会渲染，这既是优点也是坑：很多新手在代码块里写`#标题`，发现没有标题效果，然后把语法写在代码块外面，就正常了。 ### 3.4 数学公式：用LaTeX语法写公式的Markdown体验 Markdown本身不包含数学公式语法，但主流编辑器通过扩展支持了LaTeX风格的公式。行内公式用一对美元符号`$...$`包裹，块级公式用两对美元符号`$$...$$`： ```markdown 行内公式：$E=mc^2$ 块级公式： $$ \frac{-b \pm \sqrt{b^2-4ac}}{2a} $$Typora、Obsidian、Markdown Preview Enhanced都支持这种写法。不同编辑器的内部引擎是KaTeX还是MathJax，支持的命令细节略有差异，比如有些支持\begin{aligned}，有些需要额外插件。写公式遇到不渲染时，先检查是不是把所有字母都放在了$中间，再检查有没有打错反斜杠。
导出文档时，公式是最容易出问题的部分。转PDF或Word时，经常会遇到公式变成源码、字体缺失、排版错位。建议在导出前先确认目标格式的公式兼容性，Pandoc转Word时公式通常会变成Word公式，但Markdown Preview Enhanced导出PDF时偶尔需要调字体。搜索“markdown公式”能找到大量案例，十有八九都是这些细节。
3.5 任务列表：把待办事项写进文档
任务列表是无序列表的变体，语法是在-或*后面跟一个方括号，方括号里不写内容代表未完成，写小写或大写的x代表已完成：
- [ ] 整理Markdown笔记 - [x] 发布博客 - [ ] 给代码仓库补README在GitHub、Obsidian、Typora等支持交互的平台上，你可以直接点击方框切换完成状态。这个功能写项目计划、迭代待办特别好用。要注意方括号里必须有空格或x，并且再后面要有空格再接文字，否则可能被识别为普通列表，而不是任务列表。
任务列表也可以嵌套，比如在父任务下列子任务。但我个人建议不要嵌套太深，因为不同平台对任务列表的缩进支持不一致，在GitHub上三层缩进通常没问题，在微信或某些极简编辑器里，深层嵌套可能会把前面的方框弄丢。
4. 编辑器与工具选型：从纯文本到高颜值预览
4.1 三种主流Markdown编辑器怎么选
| 编辑器 | 类型 | 适合人群 | 费用 |
|---|---|---|---|
| Typora | 即时渲染 | 写博客、快速笔记、轻度文档 | 付费 |
| Obsidian | 本地双链笔记 | 知识库、个人笔记、长期维护 | 免费 |
| VS Code | 源码+预览 | 程序员、技术文档、代码仓库 | 免费 |
| Notion | 块编辑器 | 团队协作、项目管理 | 免费/付费 |
如果你追求“开箱即用”，Typora的体验最接近Word，输入#后自动变成标题，完全感觉不到Markdown的存在。缺点是需要花钱，而且它的源代码模式没有VS Code那么直观。Obsidian的优势在于本地文件管理和双链，适合做个人知识库，笔记内容都是.md文件，不怕平台跑路。VS Code则是程序员的主力，内置预览已经够用，再装插件几乎能覆盖所有高级需求。
还有语雀、飞书、知乎、掘金这类平台自带的Markdown编辑器，胜在“不用安装软件”，写完直接发布。但平台编辑器通常只支持通用语法，有些特性比如折叠块、自定义容器、数学公式支持不稳定。我的建议是：本地至少保留一个标准Markdown编辑器，平台编辑器只用来发布和快速编辑。
4.2 VS Code做Markdown需要哪些准备工作
VS Code是免费又强大的编辑器，但刚接触的朋友会疑惑“在vscode里面使用markdown要做哪些准备工作”。其实只需要准备三点：一个文件、一个快捷键、几个插件。首先新建一个.md文件，内置的Markdown预览已经能用，按Ctrl+Shift+V打开预览窗口，按Ctrl+K V可以分屏编辑。
插件方面，我的必装列表是这样的：
Markdown All in One Markdown Preview Enhanced markdownlint Paste ImageMarkdown All in One负责自动编号、目录生成、表格格式化、快捷键；markdownlint会提示你在不规范写法上可能踩的坑，比如标题后缺空格、行尾有空白字符；Paste Image让你直接粘贴截图到文档，并自动保存为图片文件。Markdown Preview Enhanced下面单开一节讲。
建议到设置里开启editor.wordWrap为on，否则长段落会横向滚动，写中文很难受。如果你要写中文字体相关的文档，还要把预览字体改成包含中文的字体，否则预览窗口可能出现方框。这些工作在VS Code里都是“配置一次，长期受益”的事情。
4.3 Markdown Preview Enhanced：预览、导出和Mermaid图
Markdown Preview Enhanced（简称MPE）是VS Code生态里最强大的Markdown扩展。它把预览和导出做成了“一条龙”：右键Markdown文件选择Open Preview，左侧编辑右侧渲染；支持导出HTML、PDF、Word、PNG；同时内置了LaTeX、Mermaid、PlantUML等渲染能力。
很多人搜“markdown preview mermaid support”，其实就是指MPE这类预览插件对Mermaid流程图的支持。你只需要在代码块的语言标记里写成mermaid，预览时就会变成一张流程图，不需要额外装图形软件。还有“markdown preview enhanced 使用prince导出乱码”这个搜索词，我实测过，导出PDF时如果你用的是PDF (prince)模式，中文字体经常乱码，原因通常是系统里没有PrinceXML默认依赖的中文字体。解决办法有两个：一是换成PDF (Chrome)模式导出，Chrome会调用系统字体，中文基本正常；二是在MPE配置里指定中文字体路径或名称。
MPE的导出功能非常实用，但我还是建议流程化操作：先用MPE把文档导出为HTML，再用浏览器打印为PDF，或者用Pandoc转Word。这样每一步都在可控范围内，而不是指着一个按钮期望搞定所有格式。
4.4 没有编辑器时，怎么用Chrome直接看Markdown
如果只是临时想查看一个.md文件，不想安装任何软件，Chrome也有办法。给Chrome装一个Markdown Viewer扩展，然后在扩展设置里开启“允许访问文件网址”，之后把.md文件拖进浏览器，或直接用Ctrl+O打开本地文件，就能看到渲染后的页面。这个扩展还支持目录、代码高亮和简单的主题切换。
有些扩展需要联网加载MathJax脚本，如果你离线查看包含公式的文档，可能渲染不出来。这时候可以改用Markdown Preview Plus，或者用一些在线的Markdown预览网站把文本粘贴进去。我个人的习惯是：临时看别人的README，直接用GitHub页面打开；本地阅读多文件笔记，还是老老实实用Markdown编辑器，浏览器扩展只是应急方案。
5. 常见问题与排查技巧实录
5.1 修改标题后发现没#号了，怎么改回来
这个问题在即时渲染型编辑器里太常见了。你以为“没有#了”，其实只是编辑器把#当作标记隐藏。在Typora里，默认实时渲染模式下输入## 标题，回车后##会消失，这时标题其实已经生效。想看源码，按Ctrl+/切换“源代码模式”，或者点菜单“视图-源代码模式”。在Obsidian里，切换到“编辑模式”而不是“阅读模式”，就能看到#。
如果你使用的是分屏预览型编辑器，比如VS Code，#不会在预览窗口出现，因为预览窗口就是渲染结果。你应该去左侧源码窗口检查，那里面一定有#。如果源码窗口里也没有，那就手动补上吧——在行首输入对应数量的#，再加一个空格，标题就会重新出现。这里最容易出错的是“#和文字之间没有空格”，比如#标题，某些渲染器会当作普通文本，预览里看起来就没有标题样式，这时不是少了#，而是少了空格。
5.2 换行始终不生效，多半是这个原因
换行不生效，先分清“换行”和“分段”两个概念。在Markdown里，想换行不产生空行，需要在上一行末尾加两个空格；想分段，则在两段文字之间空一行。新版CommonMark规范里两个空格换行是标准行为。如果你的编辑器或者发布平台把这两个空格吞掉了，比如某些微信公众号导入工具，那就用<br>。
还有一个高发场景是列表内换行。想在一个列表项里写两行内容，直接回车会让第二行变成新的列表项或普通段落，正确做法是：
- 第一行内容，行尾有两个空格 第二行内容，注意前面要有缩进如果你在Obsidian或语雀里连续按回车，发现始终连成一段，去设置里看看有没有“严格Markdown”或“智能段落”选项。有些编辑器默认启用了“软换行”，导致源码里的单个换行在预览时被保留，但导出或复制到别的平台后又恢复标准行为。解决思路很简单：写的时候把空行加上，不要依赖某个平台的软换行。格式迁移时差距最小。
5.3 表格在复制到微信或Word后变乱码
很多人搜“markdown表格复制”，基本场景是把Typora或Obsidian里的表格复制到微信、Word、飞书，结果发现变成一串|符号或者完全丢失格式。根源是目标软件不支持Markdown表格语法，它只会把表格预览的HTML复制为纯文本，而Markdown预览生成的HTML表格样式在富文本中不一定生效。
最稳妥的办法是不要直接复制。如果你用的是Typora，可以选中表格后在菜单里找到“复制为HTML”，然后在Word里选择“只保留文本”或“粘贴链接与格式”；如果你要用Pandoc，直接执行转换更容易。如果你没有命令行基础，可以先用Markdown Preview Enhanced导出HTML，再用浏览器打开HTML，手动复制表格区域粘贴到微信公众号或Word，这个流程比直接复制Markdown源码稳定得多。
我这里也提供一个笨但可靠的办法：把表格截图插入文档。虽然牺牲了可编辑性，但视觉上绝对不变形。长期写公众号或商务文档的朋友，我建议做一个固定的“Markdown转Word”工作流，见5.5节。
5.4 卡叶笔记能不能导入Markdown文本
“卡叶笔记能导入Markdown文本吗”这个问题，本质上取决于笔记软件对Markdown的支持程度。绝大多数现代笔记软件，尤其是支持本地文件管理的工具，都会提供“导入Markdown”入口。你可以在卡叶笔记里找“导入”或“设置-导入”，选择.md文件，系统通常会把它转换成笔记内容。如果不支持文件导入，也可以试试新建笔记后直接粘贴Markdown文本，看它是否自动渲染标题、列表和代码块。
如果卡叶笔记的导入结果不理想，比如图片路径丢失、层级错乱，我的建议是用一个中间格式过渡：先用Typora或Pandoc把Markdown转成HTML，再粘贴到笔记软件里。HTML是几乎所有笔记软件都能识别的富文本格式。导入后注意检查三点：标题层级是否完整、代码块是否折行、表格是否被人为切分。很多笔记软件对Markdown表格支持有限，这属于平台限制，不是你的语法有问题。
5.5 Markdown转Word工作流：从Pandoc到Coze
“markdown转word工作流coze”这个关键词，反映出越来越多人不想手动调格式，而是想用自动化工具处理。最经典的工具是Pandoc，一条命令就能搞定：
pandoc input.md -o output.docx这个命令很简单，但它能做什么远不止转换：自动识别Markdown标题、列表、表格，输出为Word原生样式。如果文档里有图片，建议加上--resource-path=./images参数告诉Pandoc图片目录位置。如果你需要统一论文格式或公司模板，还可以用--reference-doc=template.docx指定Word模板，转换结果会尽量贴近模板样式。
如果你不熟悉命令行，可以借助Coze这类工作流平台。整体的思路是：接收Markdown文本或文件，调用文档转换插件或API（比如Pandoc的在线服务），把返回的Word文件保存到云存储或本地。这样好处是能批量处理，也能和其他环节联动，比如定时拉取某个Markdown仓库，自动生成Word版本。不过自动化工作流也有坑：公式转换通常不如Pandoc原生命令稳定，大表格可能被分页切断。所以我现在的实际流程是：能用Pandoc就用Pandoc，Coze适合“不想装环境”的日常杂活。
5.6 给大模型读Markdown时要留意什么
现在很多人会把Markdown文档直接喂给大语言模型，搜索“markdown格式 llm 接收”的朋友应该都是这个场景。大模型确实能理解Markdown标记，标题、列表、加粗在语义上更容易被模型识别，但有几个地方要注意：第一，表格不要太大，一旦表格过长，模型会占用大量上下文，还可能在边界处丢失列；第二，图片引用对模型没有意义，它看不到图片内容，如果你希望模型关注图片信息，需要在文档里补充图片的文字描述；第三，代码块中的内容不要塞入太多无关日志，这会稀释文档的信息密度。
我的建议是：AI接收的Markdown文档尽量“结构化”而不是“花哨”。用清晰的标题层级、无序列表、简短段落，比大量嵌套和引用更容易让模型抓重点。如果你要求模型输出报告，也可以直接规定“用Markdown返回结果”，比如让它用二级标题组织内容，用表格输出对比项，这样后处理非常方便。换句话说是把Markdown当成一种“和AI沟通的协议”来用。
6. 几点个人经验
写Markdown这几年，我最大的体会是：别试图把所有语法一次性背完，先掌握标题、列表、链接、加粗这几样，就可以覆盖90%的写作场景。遇到不熟悉的语法，打开一个临时.md文件，左边写源码右边开预览，亲自验证一次，记忆比任何文档都牢。
还有一个很少被人注意的技巧：把源码模式和预览模式同时打开。即使你用Typora这类即时渲染工具，我也建议定期切换到源代码模式看看，确认#、*这些符号没有被误删。因为格式迁移时，唯一可信的就是源码，预览只是给你看的幻象。最后再分享一个小习惯：所有Markdown文件尽量用UTF-8编码保存，Windows旧版记事本例外；文档里的图片路径统一用相对路径。这些细节看着不起眼，真遇到乱码和图片丢失时，能帮你省下一整晚。
