1. 为什么这么多年Markdown依然是写作刚需最早接触Markdown是因为写技术方案、发社区帖子、整理开发笔记时被各种排版工具折腾得没脾气。文本复制到公众号带一堆样式粘到别的平台全乱本地记个事还得开重型编辑器。后来发现一个问题真正高效的内容创作者根本不关心排版本身他们只关心“这句话是标题还是正文”“这里要不要换行”“插图放在哪个位置”。这些需求Markdown用纯文本就能全部表达。Markdown语法说白了就是一套极其简单的“标记规则”用几个特殊符号告诉渲染器“这段文字该以什么样子展示”。它不挑平台不绑定编辑器任何支持Markdown解析的软件都能把同一份文本渲染成层次分明的页面。你写出来的文件本质上是.txt级别的纯文本但渲染出来却是结构完整的文档甚至可以直接变成网页、PDF、Word、PPT。这篇文章想做的事很直接把Markdown语法按使用频率拆开讲清楚每个语法都配上实际效果把我平时踩过的坑、试出来的技巧一并放进来。适合刚准备入门的纯新人也适合写了不少但始终没系统梳理过语法的熟手。看完可以直接照着抄。先花30秒看一个完整对照。同一段内容左边是Markdown源码右边是渲染后效果# 这是一级标题 这是**加粗**、*斜体*、~~删除线~~以及行内代码。 - 项目列表 - 第二项 这是一段引用渲染出来就是一个规范的网页排版大标题、普通段落、加粗斜体、列表、引用块全部有了。这些符号基本不增加阅读负担写的人和读的人都能一眼看懂。2. 段落到文本修饰每天都在用的核心语法这一部分是把“最常用的那批语法”一次讲透。说它们常用是因为几乎所有Markdown文档都逃不开这些符号标题、加粗、斜体、删除线、分隔线、换行。2.1 标题层级从#到######Markdown用井号数量表示标题等级# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题渲染效果就是从大到小的6级标题。实操中的建议是一篇文章最多用到四级就够了再往下层级会变得很难分辨读者也容易看晕。很多渲染器对六级标题的显示几乎和正文没区别层级的意义已经不大。## 二级标题的渲染效果 ### 三级标题的渲染效果 #### 四级标题的渲染效果注意一个细节#后面必须跟一个空格再写标题文字。写成#标题在部分渲染器里也能识别但在不少严格遵循CommonMark规范的平台上会失效。统一养成“符号后加空格”的习惯能少踩很多兼容性坑。还有个容易被忽略的点标题行的上下最好各留一个空行。如果标题和上一段文字紧紧贴在一起部分编辑器会解析出错或者后续修改时格式变得混乱。格式这种东西一旦乱了一次后面维护成本会翻倍。2.2 段落、换行与分隔线Markdown的段落规则很简朴两个段落之间用空行分隔。很多人初学时认为“只要我回车了就是换行”但实际上单次回车在多数渲染器里只是源码层面的换行渲染出来仍然是连续的一段。这里引出Markdown新手最容易踩的坑之一换行。这是第一行 这是第二行上面这样写渲染后其实是同一行“这是第一行 这是第二行”。正确换行有两种方式这是第一行 这是第二行上一行结尾敲两个空格再回车渲染出来的结果就是真正的换行。这种方式叫“硬换行”但两个空格在编辑时肉眼几乎看不见维护起来也不方便。这是第一行 这是第二行更推荐的做法是用空行把内容分成不同的段落。因为从阅读习惯来说段落之间的间距换行远比行内硬换行更清晰。分隔线是另一种高频语法三个以上的短横线、星号或下划线都能生成水平线--- *** ___渲染出来都是一条水平分隔线。注意---有点特殊——如果它出现在文字下方且上方没有空行会被解析成二级标题而不是分隔线。想避免歧义就前后都留空行。我在实际写技术文档时分隔线用得并不多。真正高频的场景是文档里要区分“正文区”和“附录区”或者在长文里放一条线提示读者“接下来话题变了”。2.3 加粗、斜体、删除线与行内代码这四类是最基础的文本修饰**加粗文字** *斜体文字* ~~删除线文字~~ 行内代码渲染效果加粗文字用于强调重要结论斜体文字用于书籍名、术语、轻微暗示~~删除线文字~~用于标记废弃方案或开玩笑式的内容行内代码用于标记命令、文件名、函数名、变量名加粗和斜体还能组合使用***加粗且斜体***实际经验是删除线慎用。在技术文档里需要向读者传达“这条方案已经废弃”时非常有用但在个人笔记里如果习惯性划掉内容过段时间回看可能完全想不起来当时为什么划掉。我通常只用删除线标注过期的替代方案正文中尽量少用。行内代码是技术写作里使用频率最高的语法之一。写API文档、配置说明、命令示例时所有机器相关的内容都应该放进反引号里。这样读者能一眼区分“这里是人话”和“这里是机器指令”。2.4 文字修饰的几个易错点第一加粗和斜体的标记符号不用刻意记忆数量记住两个原则单个星号是斜体两个星号是加粗。下划线形式的写法在部分编辑器支持不佳建议统一用星号。第二修饰符号两侧要不要加空格我的结论是中文场景下符号和文字之间不加空格。写成**重要**而不是** 重要 **。后者在部分渲染器里会出现标记符号变成文本的问题显示成带星号的奇怪内容。第三如果文字中间本身包含星号或反引号比如要显示SQL语句中的SELECT * FROM table直接写SELECT * FROM table不会出问题但如果星号紧挨着字母可能会被误判为斜体标记。稳妥做法是整句放进一个行内代码块里或者用反斜杠转义\* 星号转义转义字符在Markdown里用的频率不高但遇到需要展示语法符号本身的场景时很管用。常用转义包括\*、\_、\#、 等。3. 列表与引用结构化内容的骨架写日记可能用不上列表但写教程、技术方案、会议纪要、项目规划时列表和引用是把内容结构化的关键语法。3.1 有序列表与无序列表无序列表用短横线、加号或星号开头- 第一款 - 第二款 - 第三款有序列表用数字加点1. 第一步 2. 第二步 3. 第三步渲染效果就是一个带序号的清单。有个很好的特性有序列表的序号可以不连续或者全部写成1.渲染器会自动按顺序编号。这样调整顺序时不需要手动改数字。列表嵌套是另一个常用操作。在不同层级前加不同数量的空格或Tab即可- 一级列表项 - 二级列表项 - 三级列表项 - 回到一级规范建议是每嵌套一层增加两个空格缩进。用Tab也有效但不同编辑器对Tab的处理不一致可能出现第二层列表符号无法被正确渲染的兼容性问题。统一用空格最稳妥。3.2 任务列表笔记党的最爱任务列表是GitHub Flavored Markdown的扩展语法用方括号打勾- [ ] 待办事项一 - [x] 已完成事项 - [ ] 待办事项二渲染效果是带复选框的列表支持点击切换勾选状态在支持的编辑器里。这个功能我几乎天天用项目周报、采购清单、文章选题、Bug复现步骤全部用任务列表管理。配合文件夹级别的Markdown笔记体系完全可以替代一部分任务管理App。3.3 引用块强调外部内容引用块用开头 这是一段引文 可以有多行渲染效果是左边带竖线的缩进块。嵌套引用也支持多个叠加即可 外层引用 内层引用引用块的底层机制是“包装成另一个层级的段落”所以引用块里可以继续写列表、代码块、甚至标题。我在写产品需求文档时经常把用户原话放进引用块再把分析写在引用外这样“用户原声”和“我的判断”在视觉上立刻分开。3.4 列表与引用混排的注意事项一个常见困惑列表项里怎么放多段文字- 列表项第一段内容 列表项第二段内容开头缩进对齐即可列表项的续行需要缩进到和列表内容相同的层级否则渲染器会认为新段落不属于列表项。这个细节在笔记软件里经常出现因为很多人写完列表项后直接回车写第二段发现第二段跑到了列表外面。另一个问题是引用块里放代码 引用文字 bash npm install 代码块前后加空行和渲染出来才是干净的引用效果。如果省略部分渲染器会把代码块“挤”出引用区域。4. 链接、图片与路径痛点资源引用的正确姿势链接和图片是Markdown相对其他纯文本标记最体现便利性的部分也是网络热词里被搜索最多的话题之一。尤其是图片路径问题几乎每个新手都会在这里卡一阵子。4.1 行内式与参考式链接行内式链接最常见[链接文字](https://example.com)渲染效果就是可点击的超链接。还可以加鼠标悬停提示文字[链接文字](https://example.com 悬浮提示)参考式链接更适合文档里多处引用同一个链接的场景。先定义链接再引用[值得参考的文档][doc1] [doc1]: https://example.com/docs在文章底部集中维护所有链接地址正文部分保持清爽。这个写法在长文写作时特别好用但多数人一开始不习惯。我的经验是如果正文超过2000字且链接超过3个就改用参考式后面改链接时不用在正文里反复找。4.2 图片语法链接的变体图片语法只是在链接前加一个感叹号方括号里的文字作为图片无法加载时的替代说明也是无障碍阅读的辅助信息不要省略。点击图片跳转到链接的写法[](点击跳转的地址)日常写作中图片尺寸控制是个麻烦事。标准Markdown没有缩放图片的语法但大部分现代编辑器支持在图片地址后加CSS样式或HTML标签img src图片地址 width400 alt替代文字这是HTML直写方式。我的态度是能用HTML标签时尽量用HTML尤其是需要在不同渲染器间统一图片大小的时候。HTML的width属性在几乎所有平台都能生效而Markdown原生语法没有这个能力。4.3 图片路径的三种写法与踩坑记录图片路径是踩坑重灾区归纳起来只有三种写法相对路径图片和文档在同一个项目目录内直接用相对路径引用。本地编辑场景下最稳健Git仓库也能正常工作。绝对路径本地从根目录开始引用。适合文档和图片目录结构非常固定的项目。一旦迁移项目根目录路径很可能会失效。网络URL直接引用在线图片地址。适合写公众号、博客这类最终发布到网上的内容图片天然可访问。缺点是必须依赖外链的稳定性一旦图床关了或被防盗链整篇文档图片全裂。我踩过最深的坑是在Windows上写相对路径时用了反斜杠\换到Linux或macOS后全部失效因为Markdown路径解析遵循的是URL规则必须用正斜杠/。此外文件名里包含空格或中文也尽量改成短横线连接的英文名能少一大半奇怪问题。最好的方案是“建立自己的图片文件夹规范”——比如每篇文章对应一个images目录图片统一按日期加序号命名。这套规范帮我彻底告别了图片丢文件找不到的窘境。4.4 自动链接与锚点直接写URL有些渲染器能自动识别成链接https://example.com用尖括号包裹后可以在部分平台强制触发自动链接。文档内部跳转用锚点以页内标题的ID为目标[跳转到第2节](#2-标题文字)锚点ID在不同平台上的生成规则不太一致实际操作时如果发现跳转无效就改用HTML的id属性手动设置锚点h3 idcustom-anchor自定义锚点/h3然后链接写[跳转](#custom-anchor)这个方案在支持HTML的Markdown编辑器里都能用是我处理长文档目录跳转时的常用后备方案。5. 技术写作三件套表格、代码块与数学公式Markdown里对技术写作者最友好、也最能拉开体验差距的就是三件事表格、代码块、数学公式。这三样用好了一篇技术文档的专业度直接上一个台阶。5.1 表格语法与对齐方式Markdown表格用竖线和短横线标识结构| 左对齐 | 居中对齐 | 右对齐 | | :--- | :---: | ---: | | 苹果 | 香蕉 | 橙子 | | 10 | 20 | 30 |渲染出来是三列对齐清晰的表格。对齐方式的控制在于表头分隔行里冒号的位置:---左对齐:---:居中对齐---:右对齐---默认左对齐实际操作中表格语法最让人头疼的是换行。表格内不能直接用回车换行想换行可以用HTML的br| 功能 | 说明 | | --- | --- | | 换行 | 第一行br第二行 |另一个痛点Markdown表格语法不支持合并单元格。如果必须合并只能退回到HTML表格。我的建议是超过6列的表格就别用Markdown原生了宽度在移动端和窄屏下会很崩溃直接改用HTML表格或插图。表格还有一个使用细节表头下方那一行分隔线不能省略否则整个表格不会被识别。分隔线的短横线数量最少3个多写几个无所谓。5.2 代码块与语言高亮代码块是技术文档的核心。用三个反引号包裹python def hello(): print(Hello, Markdown!) 渲染效果是带语法高亮的代码区块。语言标识在开头反引号后面支持大多数常见语言python、javascript、bash、java、c、sql、rust、latex等。很多编辑器还支持文件名标注和行号显示例如js:src/index.js行内代码和独立代码块的区别在于行内代码用于上下文中的单个词或一句命令独立代码块用于展示多行逻辑。技术文档里两者配合使用频率非常高。 代码块的兼容性坑主要在嵌套代码块如果文档本身是教别人怎么用代码块的需要在代码块内部展示三反引号那外层就得用四反引号 markdown markdown js console.log(嵌套示例);这个技巧在写Markdown教程时几乎必用。我自己第一次写Markdown教程时完全没意识到这个坑导致整个稿件所有示例代码块全部提前截断。5.3 数学公式LaTeX语法植入技术写作免不了公式。GitHub Pages、Typora、Obsidian、Jupyter Notebook等主流平台都支持通过LaTeX语法渲染数学公式。行内公式用美元符号包裹质能方程 $E mc^2$ 是物理学最著名的公式。行间公式独立成行用两个美元符号$$ \int_0^\infty e^{-x^2} dx \frac{\sqrt{\pi}}{2} $$公式的渲染效果取决于编辑器是否配置了KaTeX或MathJax引擎。部分老牌编辑器可能完全不支持公式需要安装插件。写作时建议在公式前后加注释说明公式含义避免读者看到一堆符号直接划走。5.4 公式的常见坑LaTeX公式里一旦出现大写希腊字母、花体、矩阵这类符号语法会变得复杂。经常有人问我“为什么这个分式渲染出来特别小”其实是因为用了行内公式$...$而不是行间公式$$...$$。行内公式为了不影响文字行高渲染器会有意压缩尺寸想要大分式就必须单独成行。另一个高频报错是公式里的下划线和星号在部分编辑器中被误判为Markdown标记。所以公式内部建议统一用LaTeX语法转义$R_{max}$ 而不是 $R_max$$R_{max}$才是规范写法。这类问题在含大量下标的机器学习公式里特别常见写的时候多留个心眼。6. 扩展语法与工具链选型把Markdown用出生产力到这里基础语法已经覆盖完。但Markdown真正拉开生产力差距的部分在扩展语法。没有这些扩展Markdown只是“好用的记事本”有了它们Markdown能变成个人知识库和内容工作流的核心。6.1 目录生成的几种方式长文档最需要目录。不同编辑器方案不同Typora等桌面编辑器一般有自动大纲面板或“插入目录”功能GitHub不支持自动生成目录但可以用锚点链接手动拼接VS Code通过Markdown All in One插件一键生成VSCode里生成目录最顺手的方式是CtrlShiftP打开命令面板输入“Markdown: Create Table of Contents”插件会自动扫描所有标题并生成带锚点链接的目录列表。每次改完标题后重新执行一次同步刷新目录。这个功能对长文档编辑体验的提升非常明显。6.2 Mermaid图表让架构图和流程图告别图片Mermaid是近年最火的Markdown配套图表工具用纯文本描述流程图、时序图、甘特图等。近期的热门搜索词里“markdown preview mermaid support”上榜说明越来越多人在本地笔记里用Mermaid画图。在代码块里指定语言为mermaid即可mermaid graph TD A[开始] -- B{条件判断} B --|是| C[执行] B --|否| D[结束]渲染效果会是一张规范流程图。放在以前画这种图要么打开画图软件要么用PlantUML这类重型工具现在直接嵌在Markdown文档里跟着文本一起维护。VSCode需要安装“Markdown Preview Mermaid Support”插件才能预览。Typora、Obsidian 2.x、GitHub部分场景都已经原生支持无需额外配置。 Mermaid的常用类型至少包括 - graph 流程图 - sequenceDiagram 时序图 - classDiagram 类图 - stateDiagram-v2 状态图 - gantt 甘特图 - pie 饼图 我自己写系统设计文档时最爱用 sequenceDiagram 画接口调用链路尤其是多服务交互场景。一张时序图顶得上三百字描述。 ### 6.3 编辑器选型别在工具上纠结太久 新手最常见的误区是花大量时间挑选“最好的Markdown编辑器”。实际结论很简单编辑器只是壳Markdown语法是通用的做到“在一台新电脑上装好编辑器后五分钟内进入写作状态”才是目标。 几个常见工具的适用场景 | 工具 | 适用场景 | 一句点评 | | --- | --- | --- | | VS Code 插件 | 技术写作、代码与文档结合 | 功能最全可定制性最强 | | Typora | 纯写作、快速记录 | 所见即所得非常舒服 | | Obsidian | 知识库、双链笔记 | 生态插件丰富支持图谱 | | Mark Text | 免费开源跨平台 | 适合找Typora替代品的人 | | Jupyter Notebook | 数据分析和教程 | Markdown与代码混排 | VSCode的Markdown插件组合是我的主力方案后面第7节会给出具体配置。如果只是临时写几句话手机备忘录配上在线编辑器也完全足够不需要有工具焦虑。 从热门搜索来看“markdown编辑器推荐”“markdown下载安装教程”“vscode markdown插件”“markdown preview mermaid support 预览 快捷键”这几个问题出现频率最高。显然很多人卡在“装好了编辑器但不会预览”这一步。VS Code里预览Markdown的快捷键有两个CtrlShiftV 在独立标签页预览CtrlK V 打开侧边栏并排预览。这个快捷键是刚需中的刚需建议直接记下来。 ### 6.4 Markdown转PDF、Word与多种格式 Markdown最大的优势之一是“一次编写到处发布”。常见的转换路径 **转PDF** - Typora直接导出PDF格式还原度高 - VSCode安装“Markdown PDF”插件右键即可导出 - 命令行工具Pandoc是终极方案支持各种自定义模板 **转Word** - Pandoc一句命令就能转pandoc input.md -o output.docx - 最近热度很高的“markdown转word工作流coze”搜索词说明已经有人把转换过程做成了自动化工作流 - Typora导出Word会有轻微格式损失标题层级基本保留但表格样式需要微调 **转HTML/公众号** - 很多编辑器支持直接复制为富文本粘贴到公众号后台就能带样式 - 也可以用Pandoc转完整HTML后自行调整CSS 我自己在文档发布链路中最常用的是Pandoc。一开始觉得命令行工具门槛高后来发现它只是“一条命令解决全部格式问题”比任何图形界面编辑器都稳定。转PDF时用自带的HTML模板转Word时再用Word模板配合不同模板可以满足从技术白皮书到落地执行方案的多种格式要求。 ### 6.5 其他锁进抽屉的扩展高亮、上下标、脚注、自定义容器 部分平台还支持 markdown 高亮文字 H~2~O 是水的化学式 Emc^2^ 脚注示例[^1] [^1]: 脚注的具体解释文字高亮在部分编辑器如Obsidian、Typora生效上下标语法用~下标~和^上标^脚注为文档添加尾注进行补充说明这些语法都有平台兼容问题换个编辑器可能直接显示成原文。我的处理原则是如果文档只在某一个固定平台内使用这些扩展语法随便用如果文档需要跨平台发布就只用CommonMark标准语法加上表格、代码块、Mermaid等被广泛支持的扩展。7. 实战经验我常用的配置与踩坑记录最后这部分是真正的干货合集把前文没来得及说透的细节以及我过去几年用Markdown写作时积累的实际经验集中写出来。比起语法定义这些经验更接近“边界情况”。7.1 代码块与语法高亮兼容性代码块语言标识如果写错部分渲染器不会报错只是没有高亮。易错的有两类c#在部分编辑器里会被误解析更建议写csharpjsx和tsx在部分旧渲染器里不支持退而求其次用javascript和typescript如果文档需要跨平台使用应避免使用只在特定编辑器里定义的冷门语言标识。所有主流渲染器通用的是常见语言名比如python、javascript、bash、html、css、sql、json、yaml。7.2 我的VSCode插件组合与快捷键如果用VSCode作为主力Markdown编辑器这套组合基本够用插件名作用Markdown All in One格式化、目录、快捷键、自动补全Markdown Preview Enhanced增强预览支持导出PDF、HTMLMarkdown Preview Mermaid SupportMermaid图表预览markdownlint语法规范检查自动标出行长、缺空行等小问题Paste Image粘贴截图自动保存到本地目录并插入图片Paste Image对图片管理影响最大。安装后设置一个images目录作为存储位置截图后按CtrlAltV直接粘贴插件自动生成图片文件并写入Markdown图片语法。配合前面说的相对路径方案整篇文章的图片管理完全自动化。我常用的快捷键CtrlK V侧边栏预览CtrlShiftV独立预览AltZ自动换行ShiftAltF格式化表格需要Markdown All in One收藏这些快捷键可以省下大量切换鼠标找按钮的时间。实际写作中预览窗口一直开着、左边写右边看是最高效的工作状态。7.3 表格复制与Excel互转的实践经验热词列表里出现“markdown表格复制”“markdown表格转换excel”这两个确实是高频需求。从Excel表格直接粘贴到Markdown编辑器多数情况下会在行尾自动带Tab分隔符编辑器能自动识别成表格。但表格一旦超过4列或者单元格里有换行符自动转换基本会失败。反向操作把Markdown表格粘贴到Excel多数情况下也能实现自动分列。但更统一的方案是写一个小的Python脚本用pandas读取Markdown表格再导出Excel。一行代码import pandas as pd tables pd.read_html(doc.md) tables[0].to_excel(output.xlsx, indexFalse)这在处理批量表格转换时省时省力。我在整理季度数据报告时经常把多个Markdown文件里的表格一次性提取出来合并成一个Excel方便后续做数据处理。7.4 图片路径与附件管理的个人规范图片是Markdown写作里最大的折腾点我把自己的文件规范总结为三条每篇文章单独一个文件夹图片统一放在同一个images文件夹下文件名全部用英文小写加短横线比如network-topology.png图片在写入文档前先统一压缩到合适尺寸这样做最直接的好处是文章迁移到任何平台、任何电脑只要整个文件夹一起带走图片永不丢失。如果某天要把文件夹打包发给同事对方打开Markdown文档就能看到所有图片不需要额外找附件。这点是很多只在纯文本里写Markdown的新手完全没有意识到的。7.5 一个用于处理表格和数学公式的额外建议在科学或教学场景Markdown表格和数学公式经常同时出现。此时建议把公式放在表格之外单独讲解而不是塞进单元格里。因为表格单元格在部分渲染器中不会对齐公式公式会被裁切或换行错乱。如果确实需要在表格内放公式优先保证公式较短| 名称 | 公式 | | --- | --- | | 均值 | $\bar{x}$ |这种长度没有任何问题一旦涉及分式、求和号、矩阵考虑用图片代替或者在表格下方另开公式专项说明。7.6 一个我在排坑中发现的常见误解很多文章会把“Markdown不能办到的”和“这个编辑器不能办到的”混为一谈。比如“标准Markdown不支持缩放图片”“标准Markdown不支持高亮”这些说法在某个特定编辑器中可能是对的但换一个支持扩展语法的编辑器就完全不同。遇到某个语法在编辑器A不生效建议先查“编辑器A对CommonMark的支持程度”再查“这个语法在什么平台上是标准”。实际工作中编辑器限制不是世界限制这个判断能帮你少走很多冤枉路。我自己也犯过多次“在A里试了不生效就断定Markdown做不到”的错误后来养成了跨编辑器先确认的习惯才彻底改掉。7.7 最后分享一个懒人技巧如果你经常需要在多个设备之间同步Markdown笔记一个Git远程仓库是最好用的交通工具。在Git仓库里Markdown文件的纯文本特性可以让我们方便地对比版本内容、回退误删段落、在不同电脑间同步。写得太乱也不怕一行git diff就能看到修改痕迹这是Word文档完全做不到的。仓库同步后配合之前说的图片文件名规范就能实现“任何设备打开仓库都是完整文档”。这套组合目前是我个人知识库的底层架构稳定运行了很长时间几乎没有再因为文档崩溃或文件丢失而重启写作。
Markdown语法详解：从基础到进阶的完整实践指南
1. 为什么这么多年Markdown依然是写作刚需最早接触Markdown是因为写技术方案、发社区帖子、整理开发笔记时被各种排版工具折腾得没脾气。文本复制到公众号带一堆样式粘到别的平台全乱本地记个事还得开重型编辑器。后来发现一个问题真正高效的内容创作者根本不关心排版本身他们只关心“这句话是标题还是正文”“这里要不要换行”“插图放在哪个位置”。这些需求Markdown用纯文本就能全部表达。Markdown语法说白了就是一套极其简单的“标记规则”用几个特殊符号告诉渲染器“这段文字该以什么样子展示”。它不挑平台不绑定编辑器任何支持Markdown解析的软件都能把同一份文本渲染成层次分明的页面。你写出来的文件本质上是.txt级别的纯文本但渲染出来却是结构完整的文档甚至可以直接变成网页、PDF、Word、PPT。这篇文章想做的事很直接把Markdown语法按使用频率拆开讲清楚每个语法都配上实际效果把我平时踩过的坑、试出来的技巧一并放进来。适合刚准备入门的纯新人也适合写了不少但始终没系统梳理过语法的熟手。看完可以直接照着抄。先花30秒看一个完整对照。同一段内容左边是Markdown源码右边是渲染后效果# 这是一级标题 这是**加粗**、*斜体*、~~删除线~~以及行内代码。 - 项目列表 - 第二项 这是一段引用渲染出来就是一个规范的网页排版大标题、普通段落、加粗斜体、列表、引用块全部有了。这些符号基本不增加阅读负担写的人和读的人都能一眼看懂。2. 段落到文本修饰每天都在用的核心语法这一部分是把“最常用的那批语法”一次讲透。说它们常用是因为几乎所有Markdown文档都逃不开这些符号标题、加粗、斜体、删除线、分隔线、换行。2.1 标题层级从#到######Markdown用井号数量表示标题等级# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题渲染效果就是从大到小的6级标题。实操中的建议是一篇文章最多用到四级就够了再往下层级会变得很难分辨读者也容易看晕。很多渲染器对六级标题的显示几乎和正文没区别层级的意义已经不大。## 二级标题的渲染效果 ### 三级标题的渲染效果 #### 四级标题的渲染效果注意一个细节#后面必须跟一个空格再写标题文字。写成#标题在部分渲染器里也能识别但在不少严格遵循CommonMark规范的平台上会失效。统一养成“符号后加空格”的习惯能少踩很多兼容性坑。还有个容易被忽略的点标题行的上下最好各留一个空行。如果标题和上一段文字紧紧贴在一起部分编辑器会解析出错或者后续修改时格式变得混乱。格式这种东西一旦乱了一次后面维护成本会翻倍。2.2 段落、换行与分隔线Markdown的段落规则很简朴两个段落之间用空行分隔。很多人初学时认为“只要我回车了就是换行”但实际上单次回车在多数渲染器里只是源码层面的换行渲染出来仍然是连续的一段。这里引出Markdown新手最容易踩的坑之一换行。这是第一行 这是第二行上面这样写渲染后其实是同一行“这是第一行 这是第二行”。正确换行有两种方式这是第一行 这是第二行上一行结尾敲两个空格再回车渲染出来的结果就是真正的换行。这种方式叫“硬换行”但两个空格在编辑时肉眼几乎看不见维护起来也不方便。这是第一行 这是第二行更推荐的做法是用空行把内容分成不同的段落。因为从阅读习惯来说段落之间的间距换行远比行内硬换行更清晰。分隔线是另一种高频语法三个以上的短横线、星号或下划线都能生成水平线--- *** ___渲染出来都是一条水平分隔线。注意---有点特殊——如果它出现在文字下方且上方没有空行会被解析成二级标题而不是分隔线。想避免歧义就前后都留空行。我在实际写技术文档时分隔线用得并不多。真正高频的场景是文档里要区分“正文区”和“附录区”或者在长文里放一条线提示读者“接下来话题变了”。2.3 加粗、斜体、删除线与行内代码这四类是最基础的文本修饰**加粗文字** *斜体文字* ~~删除线文字~~ 行内代码渲染效果加粗文字用于强调重要结论斜体文字用于书籍名、术语、轻微暗示~~删除线文字~~用于标记废弃方案或开玩笑式的内容行内代码用于标记命令、文件名、函数名、变量名加粗和斜体还能组合使用***加粗且斜体***实际经验是删除线慎用。在技术文档里需要向读者传达“这条方案已经废弃”时非常有用但在个人笔记里如果习惯性划掉内容过段时间回看可能完全想不起来当时为什么划掉。我通常只用删除线标注过期的替代方案正文中尽量少用。行内代码是技术写作里使用频率最高的语法之一。写API文档、配置说明、命令示例时所有机器相关的内容都应该放进反引号里。这样读者能一眼区分“这里是人话”和“这里是机器指令”。2.4 文字修饰的几个易错点第一加粗和斜体的标记符号不用刻意记忆数量记住两个原则单个星号是斜体两个星号是加粗。下划线形式的写法在部分编辑器支持不佳建议统一用星号。第二修饰符号两侧要不要加空格我的结论是中文场景下符号和文字之间不加空格。写成**重要**而不是** 重要 **。后者在部分渲染器里会出现标记符号变成文本的问题显示成带星号的奇怪内容。第三如果文字中间本身包含星号或反引号比如要显示SQL语句中的SELECT * FROM table直接写SELECT * FROM table不会出问题但如果星号紧挨着字母可能会被误判为斜体标记。稳妥做法是整句放进一个行内代码块里或者用反斜杠转义\* 星号转义转义字符在Markdown里用的频率不高但遇到需要展示语法符号本身的场景时很管用。常用转义包括\*、\_、\#、 等。3. 列表与引用结构化内容的骨架写日记可能用不上列表但写教程、技术方案、会议纪要、项目规划时列表和引用是把内容结构化的关键语法。3.1 有序列表与无序列表无序列表用短横线、加号或星号开头- 第一款 - 第二款 - 第三款有序列表用数字加点1. 第一步 2. 第二步 3. 第三步渲染效果就是一个带序号的清单。有个很好的特性有序列表的序号可以不连续或者全部写成1.渲染器会自动按顺序编号。这样调整顺序时不需要手动改数字。列表嵌套是另一个常用操作。在不同层级前加不同数量的空格或Tab即可- 一级列表项 - 二级列表项 - 三级列表项 - 回到一级规范建议是每嵌套一层增加两个空格缩进。用Tab也有效但不同编辑器对Tab的处理不一致可能出现第二层列表符号无法被正确渲染的兼容性问题。统一用空格最稳妥。3.2 任务列表笔记党的最爱任务列表是GitHub Flavored Markdown的扩展语法用方括号打勾- [ ] 待办事项一 - [x] 已完成事项 - [ ] 待办事项二渲染效果是带复选框的列表支持点击切换勾选状态在支持的编辑器里。这个功能我几乎天天用项目周报、采购清单、文章选题、Bug复现步骤全部用任务列表管理。配合文件夹级别的Markdown笔记体系完全可以替代一部分任务管理App。3.3 引用块强调外部内容引用块用开头 这是一段引文 可以有多行渲染效果是左边带竖线的缩进块。嵌套引用也支持多个叠加即可 外层引用 内层引用引用块的底层机制是“包装成另一个层级的段落”所以引用块里可以继续写列表、代码块、甚至标题。我在写产品需求文档时经常把用户原话放进引用块再把分析写在引用外这样“用户原声”和“我的判断”在视觉上立刻分开。3.4 列表与引用混排的注意事项一个常见困惑列表项里怎么放多段文字- 列表项第一段内容 列表项第二段内容开头缩进对齐即可列表项的续行需要缩进到和列表内容相同的层级否则渲染器会认为新段落不属于列表项。这个细节在笔记软件里经常出现因为很多人写完列表项后直接回车写第二段发现第二段跑到了列表外面。另一个问题是引用块里放代码 引用文字 bash npm install 代码块前后加空行和渲染出来才是干净的引用效果。如果省略部分渲染器会把代码块“挤”出引用区域。4. 链接、图片与路径痛点资源引用的正确姿势链接和图片是Markdown相对其他纯文本标记最体现便利性的部分也是网络热词里被搜索最多的话题之一。尤其是图片路径问题几乎每个新手都会在这里卡一阵子。4.1 行内式与参考式链接行内式链接最常见[链接文字](https://example.com)渲染效果就是可点击的超链接。还可以加鼠标悬停提示文字[链接文字](https://example.com 悬浮提示)参考式链接更适合文档里多处引用同一个链接的场景。先定义链接再引用[值得参考的文档][doc1] [doc1]: https://example.com/docs在文章底部集中维护所有链接地址正文部分保持清爽。这个写法在长文写作时特别好用但多数人一开始不习惯。我的经验是如果正文超过2000字且链接超过3个就改用参考式后面改链接时不用在正文里反复找。4.2 图片语法链接的变体图片语法只是在链接前加一个感叹号方括号里的文字作为图片无法加载时的替代说明也是无障碍阅读的辅助信息不要省略。点击图片跳转到链接的写法[](点击跳转的地址)日常写作中图片尺寸控制是个麻烦事。标准Markdown没有缩放图片的语法但大部分现代编辑器支持在图片地址后加CSS样式或HTML标签img src图片地址 width400 alt替代文字这是HTML直写方式。我的态度是能用HTML标签时尽量用HTML尤其是需要在不同渲染器间统一图片大小的时候。HTML的width属性在几乎所有平台都能生效而Markdown原生语法没有这个能力。4.3 图片路径的三种写法与踩坑记录图片路径是踩坑重灾区归纳起来只有三种写法相对路径图片和文档在同一个项目目录内直接用相对路径引用。本地编辑场景下最稳健Git仓库也能正常工作。绝对路径本地从根目录开始引用。适合文档和图片目录结构非常固定的项目。一旦迁移项目根目录路径很可能会失效。网络URL直接引用在线图片地址。适合写公众号、博客这类最终发布到网上的内容图片天然可访问。缺点是必须依赖外链的稳定性一旦图床关了或被防盗链整篇文档图片全裂。我踩过最深的坑是在Windows上写相对路径时用了反斜杠\换到Linux或macOS后全部失效因为Markdown路径解析遵循的是URL规则必须用正斜杠/。此外文件名里包含空格或中文也尽量改成短横线连接的英文名能少一大半奇怪问题。最好的方案是“建立自己的图片文件夹规范”——比如每篇文章对应一个images目录图片统一按日期加序号命名。这套规范帮我彻底告别了图片丢文件找不到的窘境。4.4 自动链接与锚点直接写URL有些渲染器能自动识别成链接https://example.com用尖括号包裹后可以在部分平台强制触发自动链接。文档内部跳转用锚点以页内标题的ID为目标[跳转到第2节](#2-标题文字)锚点ID在不同平台上的生成规则不太一致实际操作时如果发现跳转无效就改用HTML的id属性手动设置锚点h3 idcustom-anchor自定义锚点/h3然后链接写[跳转](#custom-anchor)这个方案在支持HTML的Markdown编辑器里都能用是我处理长文档目录跳转时的常用后备方案。5. 技术写作三件套表格、代码块与数学公式Markdown里对技术写作者最友好、也最能拉开体验差距的就是三件事表格、代码块、数学公式。这三样用好了一篇技术文档的专业度直接上一个台阶。5.1 表格语法与对齐方式Markdown表格用竖线和短横线标识结构| 左对齐 | 居中对齐 | 右对齐 | | :--- | :---: | ---: | | 苹果 | 香蕉 | 橙子 | | 10 | 20 | 30 |渲染出来是三列对齐清晰的表格。对齐方式的控制在于表头分隔行里冒号的位置:---左对齐:---:居中对齐---:右对齐---默认左对齐实际操作中表格语法最让人头疼的是换行。表格内不能直接用回车换行想换行可以用HTML的br| 功能 | 说明 | | --- | --- | | 换行 | 第一行br第二行 |另一个痛点Markdown表格语法不支持合并单元格。如果必须合并只能退回到HTML表格。我的建议是超过6列的表格就别用Markdown原生了宽度在移动端和窄屏下会很崩溃直接改用HTML表格或插图。表格还有一个使用细节表头下方那一行分隔线不能省略否则整个表格不会被识别。分隔线的短横线数量最少3个多写几个无所谓。5.2 代码块与语言高亮代码块是技术文档的核心。用三个反引号包裹python def hello(): print(Hello, Markdown!) 渲染效果是带语法高亮的代码区块。语言标识在开头反引号后面支持大多数常见语言python、javascript、bash、java、c、sql、rust、latex等。很多编辑器还支持文件名标注和行号显示例如js:src/index.js行内代码和独立代码块的区别在于行内代码用于上下文中的单个词或一句命令独立代码块用于展示多行逻辑。技术文档里两者配合使用频率非常高。 代码块的兼容性坑主要在嵌套代码块如果文档本身是教别人怎么用代码块的需要在代码块内部展示三反引号那外层就得用四反引号 markdown markdown js console.log(嵌套示例);这个技巧在写Markdown教程时几乎必用。我自己第一次写Markdown教程时完全没意识到这个坑导致整个稿件所有示例代码块全部提前截断。5.3 数学公式LaTeX语法植入技术写作免不了公式。GitHub Pages、Typora、Obsidian、Jupyter Notebook等主流平台都支持通过LaTeX语法渲染数学公式。行内公式用美元符号包裹质能方程 $E mc^2$ 是物理学最著名的公式。行间公式独立成行用两个美元符号$$ \int_0^\infty e^{-x^2} dx \frac{\sqrt{\pi}}{2} $$公式的渲染效果取决于编辑器是否配置了KaTeX或MathJax引擎。部分老牌编辑器可能完全不支持公式需要安装插件。写作时建议在公式前后加注释说明公式含义避免读者看到一堆符号直接划走。5.4 公式的常见坑LaTeX公式里一旦出现大写希腊字母、花体、矩阵这类符号语法会变得复杂。经常有人问我“为什么这个分式渲染出来特别小”其实是因为用了行内公式$...$而不是行间公式$$...$$。行内公式为了不影响文字行高渲染器会有意压缩尺寸想要大分式就必须单独成行。另一个高频报错是公式里的下划线和星号在部分编辑器中被误判为Markdown标记。所以公式内部建议统一用LaTeX语法转义$R_{max}$ 而不是 $R_max$$R_{max}$才是规范写法。这类问题在含大量下标的机器学习公式里特别常见写的时候多留个心眼。6. 扩展语法与工具链选型把Markdown用出生产力到这里基础语法已经覆盖完。但Markdown真正拉开生产力差距的部分在扩展语法。没有这些扩展Markdown只是“好用的记事本”有了它们Markdown能变成个人知识库和内容工作流的核心。6.1 目录生成的几种方式长文档最需要目录。不同编辑器方案不同Typora等桌面编辑器一般有自动大纲面板或“插入目录”功能GitHub不支持自动生成目录但可以用锚点链接手动拼接VS Code通过Markdown All in One插件一键生成VSCode里生成目录最顺手的方式是CtrlShiftP打开命令面板输入“Markdown: Create Table of Contents”插件会自动扫描所有标题并生成带锚点链接的目录列表。每次改完标题后重新执行一次同步刷新目录。这个功能对长文档编辑体验的提升非常明显。6.2 Mermaid图表让架构图和流程图告别图片Mermaid是近年最火的Markdown配套图表工具用纯文本描述流程图、时序图、甘特图等。近期的热门搜索词里“markdown preview mermaid support”上榜说明越来越多人在本地笔记里用Mermaid画图。在代码块里指定语言为mermaid即可mermaid graph TD A[开始] -- B{条件判断} B --|是| C[执行] B --|否| D[结束]渲染效果会是一张规范流程图。放在以前画这种图要么打开画图软件要么用PlantUML这类重型工具现在直接嵌在Markdown文档里跟着文本一起维护。VSCode需要安装“Markdown Preview Mermaid Support”插件才能预览。Typora、Obsidian 2.x、GitHub部分场景都已经原生支持无需额外配置。 Mermaid的常用类型至少包括 - graph 流程图 - sequenceDiagram 时序图 - classDiagram 类图 - stateDiagram-v2 状态图 - gantt 甘特图 - pie 饼图 我自己写系统设计文档时最爱用 sequenceDiagram 画接口调用链路尤其是多服务交互场景。一张时序图顶得上三百字描述。 ### 6.3 编辑器选型别在工具上纠结太久 新手最常见的误区是花大量时间挑选“最好的Markdown编辑器”。实际结论很简单编辑器只是壳Markdown语法是通用的做到“在一台新电脑上装好编辑器后五分钟内进入写作状态”才是目标。 几个常见工具的适用场景 | 工具 | 适用场景 | 一句点评 | | --- | --- | --- | | VS Code 插件 | 技术写作、代码与文档结合 | 功能最全可定制性最强 | | Typora | 纯写作、快速记录 | 所见即所得非常舒服 | | Obsidian | 知识库、双链笔记 | 生态插件丰富支持图谱 | | Mark Text | 免费开源跨平台 | 适合找Typora替代品的人 | | Jupyter Notebook | 数据分析和教程 | Markdown与代码混排 | VSCode的Markdown插件组合是我的主力方案后面第7节会给出具体配置。如果只是临时写几句话手机备忘录配上在线编辑器也完全足够不需要有工具焦虑。 从热门搜索来看“markdown编辑器推荐”“markdown下载安装教程”“vscode markdown插件”“markdown preview mermaid support 预览 快捷键”这几个问题出现频率最高。显然很多人卡在“装好了编辑器但不会预览”这一步。VS Code里预览Markdown的快捷键有两个CtrlShiftV 在独立标签页预览CtrlK V 打开侧边栏并排预览。这个快捷键是刚需中的刚需建议直接记下来。 ### 6.4 Markdown转PDF、Word与多种格式 Markdown最大的优势之一是“一次编写到处发布”。常见的转换路径 **转PDF** - Typora直接导出PDF格式还原度高 - VSCode安装“Markdown PDF”插件右键即可导出 - 命令行工具Pandoc是终极方案支持各种自定义模板 **转Word** - Pandoc一句命令就能转pandoc input.md -o output.docx - 最近热度很高的“markdown转word工作流coze”搜索词说明已经有人把转换过程做成了自动化工作流 - Typora导出Word会有轻微格式损失标题层级基本保留但表格样式需要微调 **转HTML/公众号** - 很多编辑器支持直接复制为富文本粘贴到公众号后台就能带样式 - 也可以用Pandoc转完整HTML后自行调整CSS 我自己在文档发布链路中最常用的是Pandoc。一开始觉得命令行工具门槛高后来发现它只是“一条命令解决全部格式问题”比任何图形界面编辑器都稳定。转PDF时用自带的HTML模板转Word时再用Word模板配合不同模板可以满足从技术白皮书到落地执行方案的多种格式要求。 ### 6.5 其他锁进抽屉的扩展高亮、上下标、脚注、自定义容器 部分平台还支持 markdown 高亮文字 H~2~O 是水的化学式 Emc^2^ 脚注示例[^1] [^1]: 脚注的具体解释文字高亮在部分编辑器如Obsidian、Typora生效上下标语法用~下标~和^上标^脚注为文档添加尾注进行补充说明这些语法都有平台兼容问题换个编辑器可能直接显示成原文。我的处理原则是如果文档只在某一个固定平台内使用这些扩展语法随便用如果文档需要跨平台发布就只用CommonMark标准语法加上表格、代码块、Mermaid等被广泛支持的扩展。7. 实战经验我常用的配置与踩坑记录最后这部分是真正的干货合集把前文没来得及说透的细节以及我过去几年用Markdown写作时积累的实际经验集中写出来。比起语法定义这些经验更接近“边界情况”。7.1 代码块与语法高亮兼容性代码块语言标识如果写错部分渲染器不会报错只是没有高亮。易错的有两类c#在部分编辑器里会被误解析更建议写csharpjsx和tsx在部分旧渲染器里不支持退而求其次用javascript和typescript如果文档需要跨平台使用应避免使用只在特定编辑器里定义的冷门语言标识。所有主流渲染器通用的是常见语言名比如python、javascript、bash、html、css、sql、json、yaml。7.2 我的VSCode插件组合与快捷键如果用VSCode作为主力Markdown编辑器这套组合基本够用插件名作用Markdown All in One格式化、目录、快捷键、自动补全Markdown Preview Enhanced增强预览支持导出PDF、HTMLMarkdown Preview Mermaid SupportMermaid图表预览markdownlint语法规范检查自动标出行长、缺空行等小问题Paste Image粘贴截图自动保存到本地目录并插入图片Paste Image对图片管理影响最大。安装后设置一个images目录作为存储位置截图后按CtrlAltV直接粘贴插件自动生成图片文件并写入Markdown图片语法。配合前面说的相对路径方案整篇文章的图片管理完全自动化。我常用的快捷键CtrlK V侧边栏预览CtrlShiftV独立预览AltZ自动换行ShiftAltF格式化表格需要Markdown All in One收藏这些快捷键可以省下大量切换鼠标找按钮的时间。实际写作中预览窗口一直开着、左边写右边看是最高效的工作状态。7.3 表格复制与Excel互转的实践经验热词列表里出现“markdown表格复制”“markdown表格转换excel”这两个确实是高频需求。从Excel表格直接粘贴到Markdown编辑器多数情况下会在行尾自动带Tab分隔符编辑器能自动识别成表格。但表格一旦超过4列或者单元格里有换行符自动转换基本会失败。反向操作把Markdown表格粘贴到Excel多数情况下也能实现自动分列。但更统一的方案是写一个小的Python脚本用pandas读取Markdown表格再导出Excel。一行代码import pandas as pd tables pd.read_html(doc.md) tables[0].to_excel(output.xlsx, indexFalse)这在处理批量表格转换时省时省力。我在整理季度数据报告时经常把多个Markdown文件里的表格一次性提取出来合并成一个Excel方便后续做数据处理。7.4 图片路径与附件管理的个人规范图片是Markdown写作里最大的折腾点我把自己的文件规范总结为三条每篇文章单独一个文件夹图片统一放在同一个images文件夹下文件名全部用英文小写加短横线比如network-topology.png图片在写入文档前先统一压缩到合适尺寸这样做最直接的好处是文章迁移到任何平台、任何电脑只要整个文件夹一起带走图片永不丢失。如果某天要把文件夹打包发给同事对方打开Markdown文档就能看到所有图片不需要额外找附件。这点是很多只在纯文本里写Markdown的新手完全没有意识到的。7.5 一个用于处理表格和数学公式的额外建议在科学或教学场景Markdown表格和数学公式经常同时出现。此时建议把公式放在表格之外单独讲解而不是塞进单元格里。因为表格单元格在部分渲染器中不会对齐公式公式会被裁切或换行错乱。如果确实需要在表格内放公式优先保证公式较短| 名称 | 公式 | | --- | --- | | 均值 | $\bar{x}$ |这种长度没有任何问题一旦涉及分式、求和号、矩阵考虑用图片代替或者在表格下方另开公式专项说明。7.6 一个我在排坑中发现的常见误解很多文章会把“Markdown不能办到的”和“这个编辑器不能办到的”混为一谈。比如“标准Markdown不支持缩放图片”“标准Markdown不支持高亮”这些说法在某个特定编辑器中可能是对的但换一个支持扩展语法的编辑器就完全不同。遇到某个语法在编辑器A不生效建议先查“编辑器A对CommonMark的支持程度”再查“这个语法在什么平台上是标准”。实际工作中编辑器限制不是世界限制这个判断能帮你少走很多冤枉路。我自己也犯过多次“在A里试了不生效就断定Markdown做不到”的错误后来养成了跨编辑器先确认的习惯才彻底改掉。7.7 最后分享一个懒人技巧如果你经常需要在多个设备之间同步Markdown笔记一个Git远程仓库是最好用的交通工具。在Git仓库里Markdown文件的纯文本特性可以让我们方便地对比版本内容、回退误删段落、在不同电脑间同步。写得太乱也不怕一行git diff就能看到修改痕迹这是Word文档完全做不到的。仓库同步后配合之前说的图片文件名规范就能实现“任何设备打开仓库都是完整文档”。这套组合目前是我个人知识库的底层架构稳定运行了很长时间几乎没有再因为文档崩溃或文件丢失而重启写作。