你上手Markdown的第一周大概率会遇到几个迷惑行为明明按了回车两行字还是粘在一起表格复制到别处全乱套写好的标题突然找不到“#”了。别慌这些坑我全都踩过。今天这篇不打算把官方文档搬运一遍而是围绕markdown基本语法把日常写作最高频的用法、最容易出错的细节、以及我长期用下来的工具链和排查经验一次性讲透。无论你是要写技术文档、读书笔记、项目README还是想在博客和公众号上稳定输出内容这篇文章都值得从头到尾读一遍。废话不多说直接进正题。1. 先搞清楚Markdown到底解决了什么问题1.1 一个纯文本到处渲染Markdown最反直觉的优点是它写起来像纯文本但渲染出来是正式文档。你的源文件就是一个朴素的.md文件里面没有任何隐藏的格式信息不依赖某个特定软件才能打开。我用记事本打开一个md文件看到的仍然是干净的、带符号标记的文字不会像Word那样换个环境字体全崩、排版全乱。这个特性带来的实际好处是“一份源码多处渲染”。同一个md文件我既能导出成HTML放到博客上也能转成PDF发给同事还能贴进笔记软件变成知识库条目。遇到团队协作Git能直接帮你对比出哪一行改过了这在写版本频繁的文档时尤其有用。等你写习惯了就会觉得Word那种“文件自带一套排版”的思路反而笨重。1.2 哪些人、哪些场景真正需要它我观察下来真正离不开Markdown的主要是这几类人程序员写README、技术博客、接口文档。代码块高亮、行内代码标注都是为这个场景设计的。产品经理和运营写PRD、需求池、活动方案。用待办清单和表格梳理需求比在Word里做几十页PPT式文档高效得多。写作者和自媒体人写草稿、整理素材、排版公众号。Markdown可以一键把文字转成带层级结构的HTML粘贴到公众号编辑器再微调样式就行。学生党记课堂笔记、整理论文框架。纯文本的文件备份和检索都方便还能配合知识库软件做双链笔记。另外你会发现现在越来越多工具开始接收Markdown格式的内容很多AI工作流、文档自动化工具也把md当作标准输入格式。反正“结构化文本 纯文本存储”这个方向短期之内不会过时学会了就是长期资产。1.3 学之前先建立三个基本认知在正式学语法前我建议你先接受三个”底层设定“这样后面遇到问题能少走很多弯路。第一很多编辑器所谓的“所见即所得”本质上是把源码实时渲染给你看。你看到的标题、加粗、表格底层仍然是一堆#、**、|符号。所以遇到显示奇怪的情况第一反应永远是把模式切换到“源码 / 源代码”看清楚实际写的是什么。第二同一份md文件在不同平台上渲染结果可能会有细微差异。有些编辑器要求标题后面必须有空格有些平台把---当成分割线而非二级标题这些差异都不奇怪。写文档的时候尽量遵循更严格的写法比如#后面加空格、列表前后空行这样兼容性最好。第三Markdown管结构不管颜值。它负责的是“这是标题、这是正文、这是代码”这样的逻辑层级至于字体、字号、颜色、间距得靠主题CSS或者导出模板去控制。你只需要把层级关系写清楚把排版效果交给工具。2. 高频必会的基础语法看这一节就够2.1 标题从#到######以及那个“丢掉的#”标题语法很简单在文字前面加井号一个井号是一级标题两个是二级最多到六级# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题有两个细节比较关键。一是#和文字之间必须有空格像GitHub这种严格的渲染器#标题是不会生效的。二是标题和上一段内容之间最好空一行虽然多数编辑器不空行也能解析但空一行能避免跟其他语法混在一起出问题。热词里有人搜“markdown修改标题之后没有#了如何改回来”这个我太有发言权了。你看到的#号不见了多数情况是因为编辑器处于实时预览模式或源码/预览分离模式。比如Typora默认就是把标记隐藏只显示渲染后的效果VS Code里如果你只用预览面板当然也看不到源码里的#。这个时候只要切回“源码模式”或“分屏查看源码”符号马上就会回来并不是文件被改坏了。2.2 段落换行不是回车是“两个空格回车”这个应该是新手最容易懵的地方。在Markdown里普通的一个回车并不能让文字换行因为Markdown认为“只要是同一段落就该连续排列”。如果你在编辑器里敲了很多回车辆渲染出来可能还是一整块文字。想要真正换行有两个办法这是第一行 这是第一行的软换行行尾两个空格加回车 这是第二段和上面之间空了整整一行软换行行尾敲两个空格再回车视觉上换行但还在同一个段落里。硬换行两行文字之间空一行生成时会分成两个独立段落。实际写文档我推荐你直接用“空一行”的方式分段。因为两个空格的写法在部分平台或编辑器里会被忽略而空行是所有渲染器都认的。写诗、写歌词、写地址这种必须单行断行的情况可以用行尾两空格或者直接写br标签两种方式都管用。2.3 加粗、斜体、删除线文字强调的三种力度强调类语法的记忆成本极低这是*斜体* 这是**加粗** 这是***斜体加粗*** 这是~~删除线~~注意符号和文字之间不要加空格**加粗**是有效的** 加粗 **在某些渲染器里就会被当成普通文本。中文场景下我有一个私人习惯正文里只用加粗和删除线很少用斜体。原因是中文字体本身没有真正的斜体概念所谓“斜体”渲染出来其实是把方块字歪斜一下阅读体验并不好。加粗用于强调关键词删除线用来表示“旧方案、已废弃、待删除”这两个更符合中文用户习惯。2.4 列表有序、无序和任务清单列表是Markdown里使用频率最高的语法之一。无序列表用减号、加号、星号都能行我习惯用减号- 苹果 - 香蕉 - 子项香蕉片 - 橙子有序列表更简单1. 把大象放进冰箱 2. 关上冰箱门 3. 完成你会发现序号是手动写的1. 2. 3.但多数渲染器支持“自动递增”你全部写成1.也能按顺序渲染。我不建议偷懒因为一旦中间插入一条内容手动编号就得重排反而麻烦。任务清单本质是列表和复选框的结合- [ ] 写开头 - [x] 写完基础语法部分 - [ ] 配一张封面图[x]代表已完成[ ]代表未完成。GitHub、语雀、Obsidian、VS Code预览都支持这种写法特别适合用来做文章大纲、项目待办和初次写作时的结构化草稿。2.5 引用、分割线与代码块文档质感的来源引用别人的话或补充说明用右尖括号 纸上得来终觉浅绝知此事要躬行。 —— 我写Markdown时的内心独白引用内部也可以写标题、列表、加粗等语法组合起来能做“提醒框” **注意** 这里有个坑。很多博客里的提示块就是这么来的。分割线是三个减号、星号或下划线单独占一行---这里有个经典的坑---上面如果没有空行会被某些渲染器解析成“二级标题”而不是分割线。所以写分割线之前我总会先加一个空行稳妥。行内代码用反引号包起来适合在段内标注命令、文件名或字段名在终端执行 pandoc input.md -o output.docx 即可转换。多行代码用三个反引号包裹并在反引号后面写语言名称python print(hello world) 代码块内部是原样输出不会被Markdown解析所以贴配置文件、命令行日志都是合适的选择。如果你要在代码块里再展示代码块就用四个反引号包外层这是很多新手不知道的小技巧。3. 表格与其他进阶格式容易踩坑的地方都在这3.1 表格的完整语法表头、对齐和分隔线Markdown表格的语法并不复杂核心是竖线加分隔行| 左对齐 | 居中 | 右对齐 | | :--- | :---: | ---: | | 姓名 | 进度 | 备注 | | 张三 | 80% | 完成度不错 |第二行的---是必须存在的它告诉渲染器“上面是表头下面是表体”。冒号决定对齐方式冒号在左边就是左对齐两边都有冒号就是居中冒号在右边就是右对齐。几个容易翻车的点表格前后要空一行否则可能被当成普通文本吞掉。每一行的竖线数量要对应少一根线整个表格就乱了。单元格里的竖线|必须转义成\|否则会被当成列分隔符。单元格内想要换行可以直接写br多数平台都识别。3.2 表格复制到别处总乱我的三个处理心得热词里有人专门搜“markdown表格复制”说明被这个问题折磨的人不在少数。表格写好了想复制到飞书、语雀、Word或公众号结果一粘贴就散架。我的经验是这样的第一从源码复制到另一个md文件直接复制表格文字就行格式不会丢因为源码就是纯文本。第二从渲染预览里复制到富文本编辑器比如飞书文档、语雀、知乎最好是复制渲染后的内容而不是源码。你用Typora或VS Code预览模式看到表格鼠标选中表格区域复制粘贴到目标平台多数情况下能保留单元格结构。第三要转到Word或Excel不要手动复制粘贴直接用pandoc转格式最稳pandoc input.md -o output.docx然后打开生成的docx文件愿意的话再微调样式。公众号排版我建议用专门的md转公众号工具网上搜“markdown 转 公众号”它们会帮你把表格和代码块一起处理好比自己粘贴HTML再调样式省太多时间。3.3 锚点、脚注与折叠块让长文档更好读这三个属于“不常用但一用就回不去”的进阶功能。锚点用于页面内部跳转最常见的场景是“目录”。写法是把链接目标的标题转成小写英文空格换成连字符[跳转到第三章](#表格与其他进阶格式容易踩坑的地方都在这) [回到顶部](#1-先搞清楚markdown到底解决了什么问题)不过中文标题的锚点在各个平台支持情况不一GitHub这类平台会自动生成锚点有的编辑器则不支持中文跳转。我通常会做一份“目录”点一下能跳到对应章节这对长文阅读体验提升非常明显。脚注适合做补充说明不打断正文阅读这里有一个需要补充的概念[^1] [^1]: 这里写脚注的具体内容可以多写几句位置在文末。折叠块是GitHub等平台支持的写法特别适合做FAQ或“详细代码点开查看”details summary点击展开详细说明/summary 折叠后的内容可以包含列表、代码块等Markdown元素。 /details这个写法我已经用在了好几个技术文档的FAQ部分页面瞬间清爽很多。4. 公式、图表等硬核扩展文档专业感翻倍4.1 行内公式与块级公式的基本写法如果你写技术文章、算法笔记或者任何数学相关的文档一定绕不开公式。Markdown本身不提供公式语法但主流编辑器都内置了KaTeX或MathJax公式写法是LaTeX风格。行内公式用单个美元符号包起来质能方程写作 $Emc^2$其中 $m$ 是质量。块级公式用两个美元符号独占一行$$ \int_{0}^{1} x^2 \, dx \frac{1}{3} $$常用的命令包括分数\frac{a}{b}、上标^、下标_、根号\sqrt{x}、希腊字母\alpha \beta \gamma、求和\sum_{i1}^{n}、向量\vec{v}。写多了自然就记住了不用一次背完。注意两点一是公式渲染依赖编辑器的“数学公式开关”比如VS Code的Markdown Preview Enhanced默认开启但有的平台需要自己在设置里打开二是文章里写价格时$100这种内容会被误判成数学公式需要转义成\$100。4.2 用Mermaid画流程图、时序图和甘特图Mermaid是文本画图语法你只要把代码块的语言标记写成mermaid编辑器就会自动渲染成图形。先看流程图mermaid graph TD A[开始] -- B{条件判断} B --|是| C[处理1] B --|否| D[处理2] C -- E[结束] D -- E[结束] 再看时序图mermaid sequenceDiagram participant A as 用户 participant B as 服务端 A-B: 发起请求 B--A: 返回结果 甘特图的语法也不难mermaid gantt title 项目排期 section 开发 编码 :a1, 2024-01-01, 7d 测试 :after a1, 3d 这里有个经验不是所有平台都支持Mermaid。GitHub、语雀、Obsidian、VS Code的Markdown Preview Enhanced都支持但某些在线笔记工具不支持。在写之前先确认目标平台的渲染能力否则文档贴过去图就变成一团代码。另外VSCode里如果Mermaid预览不显示多数时候是安全设置或插件版本问题更新一下扩展再检查预览面板的网络权限就能解决。4.3 转义、HTML补充与LaTeX的边界Markdown允许直接嵌入HTML标签这是它灵活性的重要来源。比如在单元格里换行可以用br做居中可以用center插入视频可以用video标签。遇到特殊场景比如需要精确控制的间距、颜色直接写HTML是最快的补漏方案。但也别指望Markdown包办一切排版。页眉页脚、分栏、精确到像素的字号间距这些严格来说不是Markdown的活。真到了这种程度我会直接改用LaTeX或Word模板而不是在Markdown里硬抠样式。转义是另一个容易被忽略的基础能力。如果你想让某些特殊符号显示为普通字符在它前面加反斜杠\# 这不是标题 \* 这不是列表 \ 这不是引用小到写代码文档大到写数学博客这套“基础语法 扩展公式 Mermaid图”的组合基本能覆盖日常90%以上的需求。5. 编辑器选型与常见问题排查实录5.1 编辑器怎么选我试过一批之后留下的方案工欲善其事必先利其器。Markdown编辑器太多我根据场景给一张选型参考表编辑器特点适合人群Typora即时渲染界面干净隐藏标记符日常写作、博客草稿MarkText开源免费类似Typora更新较慢预算有限但想要好体验Obsidian本地文件库双链笔记插件丰富知识管理、卡片笔记VS Code 插件可编程、扩展多、对Git友好程序员、技术文档语雀 / 飞书在线协作国内访问快自带md块团队协作、知识库Chrome扩展浏览器直接渲染本地md文件临时查看文件选型的关键不是“哪个最好”而是“你主要拿来干嘛”。写博客草稿我推荐Typora类工具搭笔记体系我用Obsidian给项目写READMEVS Code顺手就能搞定。有人问我某个小众笔记软件能不能导入md文本其实多数笔记类工具都在设置或导入功能里藏着“导入Markdown”的入口找不到就多翻翻导入/导出菜单这功能比你想的普及率更高。5.2 VS Code写Markdown的准备工作清单VS Code本身不带Markdown预览能力装插件是必需品。我每次在新机器上配环境的步骤基本固定安装扩展Markdown All in One表格格式化、自动目录、快捷输入、Markdown Preview Enhanced增强预览、导出PDF/HTML、Paste Image截图后直接粘贴到文档并保存为本地图片、markdownlint语法规范检查。调整设置在settings.json里加上自动推测编码避免打开别人的md文件乱码{ files.autoGuessEncoding: true }习惯用快捷键CtrlShiftV在当前页面打开预览CtrlK V开启分屏预览左边写右边看效率翻倍。图片路径规划用Paste Image插件时建议把图片保存到当前文档目录下的images文件夹并使用相对路径引用。这样整个目录拷走时图片不会散放到Git仓库也能正常显示。“在vscode里面使用markdown要做哪些准备工作”这个问题经常被问到其实就三步装插件、设编码、建好图片目录。做完这三件事VS Code就是一个足够好用的Markdown写作环境。5.3 导出PDF乱码和其他高频问题速查热词里有一个非常具体的痛点“markdown preview enhanced 使用prince导出乱码”。我遇到过也把它解决了。Markdown Preview Enhanced导出PDF有不少方式其中Prince导出速度快但对中文字体支持比较弱。解决思路很简单给MPE的导出样式指定中文字体。你可以在文档的front-matter里配置也可以在设置里自定义export样式核心是给body指定一个中文字体族比如PingFang SC、Microsoft YaHei、Noto Sans CJK SC之一。如果Prince方案搞不定我更推荐稳定的兜底方案pandoc input.md -o output.pdf --pdf-enginexelatex -V CJKmainfontPingFang SC或者最朴素的办法先导出HTML用Chrome打开后“打印 → 另存为PDF”中文字体显示基本不会出错。最后把平时会被频繁问到的问题整理成一个速查表问题现象检查项解决方案换行不生效行尾是否只有回车改为行尾两空格或直接空一行分段标题前没有#号是否处于实时预览模式切换源码模式查看表格渲染乱掉分隔行是否存在、竖线数量是否一致补全图片显示不出来路径是否为相对路径、文件名是否含空格修正路径避免文件名里有特殊符号导出PDF中文乱码字体未指定用XeLaTeX并指定CJK主字体浏览器打开md是纯文本未装渲染插件安装Markdown Viewer类扩展代码块没有高亮三个反引号后是否写语言名改为python这类写法文件打开就乱码编码不一致设置autoGuessEncoding或用UTF-8重新保存还有一个容易忽略的习惯文件名尽量别用中文空格和特殊符号跨平台拷贝、上传下载时极容易出问题。我用字母、数字、下划线命名md文件文档内部标题随便写中文两者并不冲突。我自己用Markdown这几年最大的经验是别把它当“排版软件”而是当“写作环境”。语法真正常用的就那么几样遇到不会的临时查一遍写多了就成了肌肉记忆。真要说有什么秘诀那就是每写一个长文档前先把这个文档的标题层次、需要哪些表格、要放几张图想清楚然后用Markdown的结构把思路搭出来后面填内容就顺多了。希望这篇能帮你少踩几个我当初踩过的坑。