Markdown语法详解：从标题代码块到图片路径的完整写作手册-北京尧图网络

1. 为什么我现在劝每个写文档的人都学一下Markdown1.1 一个被排版逼疯的人是怎么入坑Markdown的Markdown这玩意儿我用了快十年每天写博客、写技术方案、记开发笔记、在论坛回帖子都在用这套语法。最早接触它纯粹是被Word折磨得没脾气——写一篇带代码的文档一会儿要调字体一会儿要调缩进一会儿表格又错位了光排版就能耗掉半小时。后来在一个开源项目的README里第一次看到那种井号开头、星号结尾的纯文本写法渲染出来的效果还格外清爽当场就惊了原来写文档可以这么轻。用Markdown写东西本质上就是不关心排版只关心内容和结构。你写的每一行字就是一个个带有含义的记号比如#代表这是一级标题-代表这是一个列表项这些记号本身也是纯文本放在任何设备上都能打开、都能看懂。正是因为这种特性Markdown成了程序员社区、文档协作工具、博客平台几乎通用的标记语言甚至可以说不会Markdown的写作体验在现代内容生产流程里是吃亏的。这篇文章要聊的就是Markdown的基础语法从最常用的标题、段落、强调、列表、引用到代码块、表格、图片链接再到踩坑频率最高的换行和图片路径问题。我会结合自己这几年实际写文档攒下来的经验和教训把这些语法点讲透讲细顺便聊聊编辑器选型和常见的导出转换玩法。不管你是刚入门的小白还是用了很久但一直没系统整理过语法体系的老手这篇文章都适合你当一份可随时查阅的手册。1.2 Markdown到底解决了什么问题它的定位和其他格式有什么区别很多人第一次接触Markdown会有一个疑问我为啥要学一种新语法直接Word、OneNote甚至纯记事本不好吗关键差异在于Markdown是“内容与样式分离”的。你在Markdown源文件里看到的是结构化的纯文本一旦放到支持Markdown的编辑器或平台里它又会自动渲染成带层级的漂亮排版。这意味着同一份.md文件可以灵活出现在GitHub的README里、博客后台的编辑框里、团队的wiki系统里甚至通过工具把它转成Word、PDF、HTML而完全不改变它的内容和结构。从工作流的角度看Markdown还有一个杀手级优点它非常适合版本管理。因为本质是纯文本一行一行的内容差异可以被Git这类工具精准识别团队协作改动文档的时候谁改了哪句话、什么时候改的一目了然。这一点我在公司没少受益——产品文档和技术方案用Markdown管理比多人同时在Word里改来改去高效太多了。还有一点容易被忽略Markdown的生态极其成熟。主流博客平台、社区论坛、知识库工具、代码托管仓库绝大多数都原生支持Markdown渲染学习成本又低到半小时就能上手。所以把它当作自己写作工具链的“地基”怎么想都是划算的。2. 先把手里的工具准备好编辑器选型与MD文件打开姿势2.1 新手最省心的组合Typora、VS Code和在线方案怎么选工具决定体验这一点在Markdown上体现得特别明显。同一个.md文件在不同编辑器里的观感可能差很多所以选一个顺手、渲染能力强的编辑器是学习语法的第一步。我自己的主力工具是Typora。它的最大特点是“所见即所得”输入#和文字之后回车的一瞬间就自动变成标题样式不需要分栏预览写起来特别顺手。支持主题换肤、图片粘贴自动保存导出PDF和Word也很方便。不过Typora自从收费之后很多人会去找平替。VS Code则是另一个几乎绕不开的选择。你可以把它当作纯文本编辑器打开.md文件加上一个Markdown All in One插件之后右侧就能实时预览渲染效果。VS Code的优势在于它是一个综合体——写Markdown的同时旁边可能同时开着代码文件、终端、Git面板对程序员来说极其顺滑。如果你平时工作离不开VS Code直接在它里面写Markdown是最稳的方案。如果你是临时用一下或者完全不想安装软件我建议直接走在线方案。GitHub的仓库文件预览、掘金和知乎编辑器、语雀文档、notion、markdown.so这类在线编辑器打开就能粘贴Markdown源码直接看到渲染结果非常适合快速验证某个语法标记的写法。日常写短小的笔记我经常直接开一个StackEdit或者Dillinger零安装零负担。2.2 MD文件怎么打开本地、编辑器与系统默认程序的三条路拿到一个.md文件却双击打不开这是我在各种交流群里被问过最多的问题之一。原因在于.md文件本质上是一个纯文本文件但操作系统不认识这个后缀默认可能会用记事本打开也可能弹出“选择打开方式”更有甚者直接报错。最朴实的方式是右键文件选择“打开方式”然后选一个纯文本编辑器。Windows上用记事本看源码没问题macOS上用TextEdit也能看只是看不到渲染效果。想让排版效果直观呈现还是得靠带Markdown渲染能力的工具。如果你高频接触Markdown文件建议直接把默认打开方式绑定到你的编辑器上。Windows上可以在更多应用中固定Typora或VS CodemacOS则在“显示简介”里修改默认应用程序。之后双击.md文件就能直接进入编辑状态省去每次右键选择的过程。还有一种情况是你在手机或平板上收到一个.md附件手机自带的备忘录未必能做好渲染。我常用的做法是装一个支持Markdown的笔记类App比如语雀、Obsidian、纯纯写作等导入后即可阅读和编辑。这类App普遍支持保存云端笔记也适合顺手用手机碎片时间记录想法。2.3 不想装软件在线预览和三方阅读器的常见路线遇到偶尔看一眼文件内容的需求比如同事发来一个.md文档你只是想知道里面写了什么这时候安装一个完整编辑器反而显得多余。我一般直接丢进在线的Markdown预览网站比如Markdown Live Preview、dillinger.io粘贴或上传后立即看到渲染效果。如果你在Linux服务器上工作没有图形界面只有命令行也有非常轻量的阅读工具。像glow、mdcat、rich-cli这类命令行工具可以在终端里直接把Markdown渲染成带颜色的排版输出非常适合快速审查文档。平时看项目代码仓库里的README用glow打开是真的很香。另外提醒一句浏览器也是现成的Markdown查看器。只要装一个Markdown Reader之类的扩展拖入本地的.md文件Chrome和Edge就能直接渲染预览不需要专门的软件。这个方案对“偶尔看一下内容”的场景非常高效。3. Markdown核心语法拆解从标题到代码块的完整实操3.1 标题与段落最基础也最容易出错的换行问题标题是Markdown最直观的语法。在行首加不同数量的井号#就产生不同级别的标题一个井号是一级标题两个是二级以此类推直到六级。实例如下# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题标题后建议加一个空格再接文字如# 标题这是大多数解析器的惯例写法也避免了极少数编辑器不识别的问题。不过我实测下来绝大多数主流的Markdown渲染器就算不加空格也能识别只是写规范点总没坏处。另外一个比较隐蔽的坑是标题与标题之间要不要空行多个标题连着写是可以的但如果你想让标题后面跟一段正文标题和正文之间建议留一个空行因为有些解析器会认为标题后的紧接行属于标题本身。段落应该是所有语法里最容易理解的一行或者连续多行文字就是一段。但“换行”问题几乎能排进Markdown新手迷惑行为前三名。你在源码里敲了一个回车渲染出来后居然没有换行这背后其实是Markdown对“软换行”和“硬换行”的区别处理。简单来说在一段文字中间按一次回车渲染时会被当成一个空格而不是换行。想真正换行有几种做法在本行结尾加两个空格然后再回车Markdown会渲染成一个换行直接空一行让这行文字成为新段落这是最常用、最保险的方式使用HTML的br标签强制换行少数支持HTML的渲染器可用。实际写博客和笔记时我不太推荐每行结尾补两个空格因为这种不可见的字符容易在复制粘贴过程中丢失。更推荐的做法是在需要分段的地方主动空一行让结构更清晰。如果你是处女座性格希望排版逼格高一点还可以试试段与段之间全用空行隔开渲染出来的文档观感会清爽不少。3.2 强调、列表、引用写正文时最高频的三个语法写正文时强调语法几乎每天都在用。用一对*或_包裹文字代表斜体用两对代表粗体用两对波浪号~~代表删除线这是*斜体* 这是**粗体** 这是***斜体加粗*** 这是~~删除线~~这里有个细节值得注意*和_在某些场景下的边界判定不一样。如果文字中间夹着下划线比如变量命名foo_bar_baz用_做强调符号时可能无法正确识别我习惯统一用*来写斜体和粗体跨平台兼容性最好。列表分为无序列表和有序列表。无序列表用-、*、开头加空格有序列表用1.开头加空格。嵌套列表则是在内层项前加两个或四个空格再写标记。我自己在写需要分步骤说明的内容时几乎只用有序列表因为阅读者能轻易把握流程顺序。列表最常踩的坑有两个。第一个是列表与列表之间的空行问题有的引擎要求列表前后各留一个空行否则无法正确渲染成列表样式。第二个是混合使用不同标记时可能出现的分裂比如前三条用了-第四条用了*在某些严格的解析器里会渲染成两个列表。建议一个列表内部统一使用同一种标记符号。引用是通过行首加实现的块级引用用多个嵌套引用内的段落要保留空行才正确。写引用内容时我习惯在右尖括号后面留一个空格实际渲染更稳定这是一级引用这是二级引用引用段落之间也需要空行。这里的引号也经常用来标注注意事项、摘录别人观点以及标记一些“额外补充”的内容视觉上和正文区分度很高。3.3 链接、图片、分割线让文章完整起来的拼图链接的写法是[显示文字](URL 可选标题)。可选的标题在鼠标悬停时会出现提示虽然大多数人不会写这个标题但在需要给读者更多信息的时候还是很实用的。如果链接需要被多次引用Markdown还支持引用式链接文末统一集中维护目标地址[博客地址][blog] [blog]: https://example.com图片和链接极其相似只是前面多一个感叹号![图片描述文字](图片路径可选标题)图片的“描述文字”在图片正常显示时看不见但图片加载失败时会显示同时它对屏幕阅读器极其友好所以不能偷懒省掉。关于图片路径的问题后面单独展开讲因为它算是Markdown学习过程中翻车率最高的一关。分割线用三个或以上的-、*、_单独成行即可。这里有个容易踩的坑如果在一行只写一个-某些编辑器会把它识别成无序列表而不是分割线。三个连续的-虽然保险但要注意和前面段落之间最好留一个空行否则会渲染成二级标题而不是分割线。基于我的个人习惯来说分隔线不宜滥用。文档里如果大量使用---读起来会像一条条断开的马路不如用空行和标题把文章结构自然撑起来。3.4 代码块与行内代码技术文章的核心刚需Markdown在处理代码方面的优势是Word无法企及的。行内代码用一对反引号包裹适合强调变量名、文件名、命令等简短内容请执行 python main.py 命令。如果行内代码本身又包含反引号可以用两个反引号来包裹 code 片段块级代码则用三个反引号包裹这是技术文章里最常用的语法之一python def hello(): print(hello world) 反引号后面的语言名可以指定代码高亮主题不同平台支持的语法高亮不完全一致但常用的python、javascript、bash、json、text基本上都覆盖到了。写代码块时还有个细节代码块起始的三个反引号必须顶格写前面不要有空格否则可能被当成普通文本处理。我自己写文档时凡是涉及命令、配置文件和关键代码片段一律指定语言标识这样读者拿到源码复制到自己的编辑器里高亮也是正确的。代码块内部不需要手动转义HTML也不用担心Markdown标记生效这在写教程时太方便了。3.5 表格、任务列表和转义字符进阶但必须掌握表格是Markdown语法里长得最不直观但也实用的一种。它用|分隔各列第二行用---分隔表头和内容示例如下| 项目 | 说明 | 状态 | | ---------- | ---------- | ------ | | 标题 | 一级标题 | 已完成 | | 图片路径 | 相对路径 | 待验证 |表格的对齐方式通过第二行的冒号位置控制| 左对齐 | 居中对齐 | 右对齐 | | :----- | :------: | -----: | | 1 | 2 | 3 |表格语法看起来简单但有个非常影响体验的坑表格前后必须保留空行否则Markdown可能不会渲染成表格而是把这一堆竖线和短横线原样输出成文本。这是我刚接触表格语法时印象最深的一个翻车场景。任务列表扩展自列表语法用- [ ]表示未勾选- [x]表示已完成。它非常适合写待办清单、功能checklist和需求评审记录- [x] 完成语法学习 - [ ] 练习图片相对路径转义字符往往被忽略但偶尔救命。如果你想在文章里展示#、*、、|这些语法标记本身而不是让它们被解析成格式需要在前面加反斜杠\。比如写\# 标题渲染出来就是你想要的字面内容。我在写讲解Markdown语法的文章时几乎每篇都会用到转义否则举的例子会被渲染器“吃”掉。4. 那些文档里没写透的细节图片路径、表格复制与数学公式4.1 图片路径的几种写法以及为什么你的图片总是裂掉图片不显示是Markdown用户遇到最多的“灵异事件”之一。排查来排查去你会发现十有八九都是路径问题。Markdown里的图片路径分绝对路径、相对路径和网络URL三种。绝对路径写的是/Users/name/pic.png这种从根目录开始的完整路径在本机用没问题但文件移动或交给别人后就失效了。相对路径相对的是当前Markdown文件所在的目录比如同目录下的图片可以直接写./pic.png上一级目录的图片用../images/pic.png。这种写法在Git仓库、文档项目里是主流文件跟着仓库走到哪都能正常显示。还有一种是直接写完整的网络地址比如https://example.com/pic.png适用于图床或网上现成的图片。这种方式最稳定不依赖本地文件但前提是网络地址能正常访问且浏览器/编辑器没有被屏蔽对应域名。实际写文档时我常用的策略是图片如果量少放同目录下的images文件夹相对路径引用如果量多且项目常迁移先集中到图床管理写网络URL。还有个小细节路径里有空格和中文时某些编辑器可能无法识别稳妥的处理方式是给URL加上尖括号比如![图](../images/我的图片.png)或者干脆把文件名改成字母和数字组合。粘贴图片也算一个高频需求。Typora和VS Code都支持直接把剪贴板里的图片粘贴到文档里并自动保存到指定目录。如果你用的是不支持自动保存的编辑器粘进来的图片可能只是一个本地临时路径换机器之后必然裂掉。所以我坚持用支持自动保存图片的编辑器处理带图片的文档。4.2 表格复制到Excel、MD转Word的实战方案很多人会问Markdown写的表格怎么复制到Excel里直接用复制粘贴通常是一件灾难——表格单元格被混在一行文本里根本分列。我的经验是先借助外部工具处理。最简单的方案是复制Markdown表格源码粘贴到在线转换工具里比如Table Convert、ConvertSimple这类网站选择导出为CSV或Excel格式然后再把CSV导入Excel列和行就整整齐齐了。如果你本地装了Pandas也可以直接用Python读表格数据再导出Excel适合批量处理大量表格的场景。把Markdown转成Word时Pandoc是绕不开的利器。它的基本命令很简单pandoc input.md -o output.docx这条命令会把整个Markdown文档转换成Word包括标题层级、表格、代码块而且转换效果相当不错。日常写周报和技术方案时我常常先用Markdown起草内容再一次性导出成Word交给同事或领导效率和排版都很在线。如果想转PDF推荐走两段式先转HTML再用浏览器的打印功能输出PDF。这样生成的PDF排版可以由浏览器主题决定代码高亮和表格样式都比较美观。4.3 数学公式插件与流程图扩展Markdown的边界在哪Markdown基础的边界感不太清晰很多扩展语法在某些渲染器里可用换一个环境可能就失效。数学公式是比较常见的一种扩展语法基于LaTeX分两种行内公式用一对$包裹块级公式用两对$$包裹。比如行内公式$\alpha \beta 1$ 块级公式 $$ \int_a^b f(x)\,dx $$在Typora、笔记类软件和有MathJax/KaTeX支持的渲染器里这套公式能正常显示。但换到GitHub或知乎这种平台默认情况下不一定支持需要确认平台是否启用数学公式渲染。有道云笔记则支持画流程图语法是mermaid块可以画简单的流程和时序图不过同样依赖平台支持。看到这里你应该明白了Markdown并不是一个一成不变的规范而是一个生态。最核心的语法是CommonMark它定义了大家普遍遵守的基线GitHub又有自己的风格叫GFMGitHub Flavored Markdown在CommonMark基础上加了任务列表、表格、删除线等扩展。在写作时如果内容将来要在多个平台发布尽量只使用CommonMark范围内的语法这是最稳妥的。5. 常见问题排查与避坑实录5.1 换行失效、列表错乱、表格不显示问题都出在这些地方我总结过这些年被问到的Markdown高频问题基本可以浓缩成以下几个换行失效是最常见的一个。你写了文字然后回车渲染出来居然没换行。原因在3.1里已经说过Markdown把单个回车当成空格。解决方式就是用空行分段或者行尾加两个空格。我个人推荐空行因为两个空格对肉眼完全不可见一旦删除或复制到别处换行效果就丢了。列表错乱往往是因为标记符号混用、缺少空行导致的。修复办法是统一列表符号列表与其他文本之间留出空行。有序列表自动编号时还有个尴尬情况如果你把每行都写成了1.有些渲染器会按顺序递增编号有些则会全部变成1。想控制编号顺序就老老实实按数字写。表格不显示或者显示成纯文本基本上都是因为前后没空行或者表头分隔行太短。分隔行至少要写三个-并且列数要和表头一致。还有一个冷门坑表格单元格里的|如果没有转义会被当成列分隔符整行的列数突然变多表格直接乱掉。处理方式是把单元格内的竖线写成\|。5.2 不同编辑器之间的兼容性差异以及我的应对策略困扰Markdown使用者最深的问题很多时候不是某个语法不会写而是同一个.md文件在不同环境里渲染结果不一致。差异主要在几个层面换行符的处理方式不同Windows习惯\r\nLinux和macOS习惯\n绝大多数现代编辑器会自动识别但老旧的记事本可能会显示成乱成一团。扩展语法的支持不同表格和任务列表这种扩展语法在GitHub上支持得很好但在极简渲染器里可能被当作纯文本。图片相对路径的解析基础不同有的编辑器有单独的文档目录有的则把图片路径看作全局这就导致同一个文件换一个编辑器图片就裂了。我自己的应对策略有三条一是写作时尽量使用CommonMark基础语法避免太依赖某款编辑器的私有扩展二是在标题、列表、引用、图片等关键语法之后都加空行包容不同解析器的差异三是遇到重要文档会在提交前用至少两个渲染器过一遍比如Typora和VS Code的预览各看一次再决定是否发布。这套习惯帮我少踩了不少坑。最后再分享一个小技巧给大家。如果你希望自己的Markdown水平不只停留在“会用”而是“用好”可以多去读一些高质量开源项目的README和Docs文档。一边读一遍拆解它的标题层级、代码块标注、表格组织方式很快就能形成自己的一套写作范式。我自己最初的那套文档规范就是模仿一个知名开源仓库的文档结构拆出来的一直沿用到现在。Markdown语言本身不复杂真正值得投入时间的是你用它组织信息的能力。

Markdown语法详解：从标题代码块到图片路径的完整写作手册

相关推荐

awesome-free-models API路由指南：LiteLLM与9Router统一接入多家免费大模型

防止 Agent 工具返回被逆向投毒：针对 Tool Outputs 的间接注入深度审计

Flowable工作流引擎数据库访问机制全解析：MyBatis整合、表结构与性能优化

更多资讯

STM32F091RC驱动MR25H40CDF MRAM：从原理到工业级应用

VHDL基本程序框架详解：实体、架构体与端口设计

DeepSeek证券研报自动化：从数据对齐到合规回检的落地实践

PX4固件移植指南：自制STM32H7飞控从硬件到调试全流程

手语视频识别实战：YOLOv5+MediaPipe构建基于USTC数据集的手势分类系统

详解Ceph块存储：从cephadm集群部署到RBD挂载与生产避坑

今日更新

插件加载失败深度解析：从did not activate到生命周期排查指南

SpringBoot+Vue+MyBatis企业级房屋租赁管理系统源码解析

企业核心数据灾备自动化：用 OpenClaw 备份到本地 + 云端 + 离线存储的 TaoToken 统一通道实践

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？