我最早接触 Markdown还是在写技术文档的时候。当时被 Word 的排版折磨得够呛每次调格式都要花老半天后来换成了纯文本的 Markdown一下子就回不去了。这么多年下来无论是写博客、记笔记、写 README还是整理自动化脚本的说明文档我几乎都离不开这层极简的标记语法。很多人一听语法两个字就头皮发麻觉得又是 Python、C 那一套难啃的东西其实 Markdown 的语法规则非常简单认真学下来半小时足够但它能帮你省下的时间是往后每一篇文档、每一条笔记都会持续兑现的。这篇文章就从基础用法讲到进阶工作流把标题、换行、列表、代码块、图片路径这些最容易被坑的细节全部拆开说清楚也会聊到数学公式、Callout、表格转 Excel、Markdown 转 Word 这些高频场景。不管你是刚接触 md 语法的纯新手还是已经写了一阵子但总遇到格式问题的老用户都可以照着里面提到的方案直接抄作业。1. 为什么学 Markdown 而不是继续用 Word核心思路与整体设计1.1 语法的本质就是一套排版语法糖学任何东西之前先把为什么想明白后面才不至于学完就忘。Markdown 这套语法规则的底层逻辑就是用尽量少的符号表达尽量多的排版意图。你可以把它理解成一种语法糖原本在 Word 里要点击工具栏才能完成的加粗、标题、列表、引用在 Markdown 里只要在文字前后加上**、#、-、这些标记就够了。如果你之前接触过 Python、Shell、C、TypeScript 这些语言的基础语法会发现它们都有一个共同特点语法规则本身不复杂难的是怎么组合起来解决实际问题。Markdown 也是一样单个规则很简单组合起来就能写出结构清晰、层次分明的文档。写 Markdown 的时候你的手不需要离开键盘去摸鼠标思路也不会被排版打断这就是它最核心的吸引力。1.2 适用范围比你想的更广Markdown 不是程序员专属。我见过产品经理用它写需求文档作者用它写书稿学生用它做课堂笔记运营用它整理选题库。只要是需要纯文本承载结构化内容的地方它几乎都适用。具体来说我平时最常用的场景有这几类写技术博客和项目 READMEGitHub、GitLab 对 Markdown 的原生支持非常完善提交代码后文档自动渲染省去部署博客系统的成本。做个人知识库Obsidian、Notion 这类笔记工具都支持 Markdown笔记之间还能互相引用比传统 Word 文档灵活太多。写自动化脚本的说明文档写完一个 Python 脚本或者 Shell 脚本同目录下放一个README.md把用法、参数、注意事项写清楚。很多时候 pipeline 脚本里也会用 Markdown 语法来生成报告文本方便后续直接展示。日常沟通和协作在飞书、钉钉、语雀里Markdown 语法大多能直接生效尤其是代码块和列表沟通效率提升非常明显。1.3 一个统一的心智模型用纯文本表达结构化内容学 Markdown 最需要建立的是一个统一的心智模型你写的是纯文本但通过特定符号渲染引擎会把它变成带格式的页面。这个模型一旦建立后面遇到任何不支持的功能你都可以用最原始的办法解决——直接改文本标记或者混入 HTML 标签。比如你在某些不支持 Markdown 的平台上想要一个不一样的标题样式可以直接写h3标题/h3大多数渲染引擎都会认。这种纯文本为底、标记为骨的设计让 Markdown 能适应各种环境也是它十几年经久不衰的根本原因。2. 基础语法拆解与实操要点2.1 标题、段落和换行的正确姿势标题是最好学的#的个数代表标题层级一个#是一级标题两个#是二级标题最多六个#。注意#后面要加一个空格再写文字否则某些渲染器不会识别。我见过不少新手在#标题这样写结果怎么都不生效其实就是差了一个空格的事。段落更简单一个空白行隔开就算另起一段。但这里有个超级常见的坑单次回车不会换行。在大多数 Markdown 引擎里你敲一个回车渲染出来还是同一行想要真正换行有两种方式在行的末尾加两个空格再按回车直接空一行让文本成为两个段落。第二种方式更常用因为两个段落之间会有明显的间距视觉上更清楚。还有一种特殊情况是 HTML 里的br标签在某些不支持行尾空格的平台比如部分论坛很管用。提示在 Typora 这类所见即所得的编辑器里单个回车会直接显示为换行但导出到其他平台后可能就变了。所以最稳妥的做法是养成空一行分段的习惯。2.2 强调文字粗体、斜体与删除线强调语法是 Markdown 里最像语法糖的部分记起来非常容易粗体**文字**或者__文字__斜体*文字*或者_文字_粗体加斜体***文字***删除线~~文字~~实际写作的时候我个人建议统一用**和*尽量避免__和_。原因很简单下划线在文件名、链接文字、代码变量名里太常见了。比如你写_file_name_本来想斜体结果渲染出来可能整个乱掉。用*就没这个烦恼。强调语法看起来不起眼但用好了文档的阅读体验会提升一个档次。我的习惯是加粗只用来标记真正重要的结论斜体用来补充说明删除线偶尔用在更新记录里不要一句话里到处都是加粗那样反而没有重点。2.3 列表有序、无序与嵌套任务列表是 Markdown 里使用频率最高的语法之一。无序列表用-、*或者开头有序列表用1.、2.这种编号开头。这里有一个细节有序列表的序号其实不需要你手动排正确因为大多数渲染器会按顺序自动编号。所以你完全可以全部写成1.渲染出来依然是 1、2、3。不过建议还是手动写对因为有些平台导出时会读取原始数字。嵌套列表的写法是子列表前缩进两个或四个空格。很多新手在这里出问题缩进不一致导致层级错乱。我的经验是嵌套列表必须用统一的缩进量要么全部两个空格要么全部四个空格混着来必乱。任务列表是 GitHub 风格的一种扩展写法是在无序列表的基础上加上[ ]或[x]- [ ] 待办事项 A - [x] 已完成事项 B这个语法在笔记软件里特别实用我每天的工作清单就是用它管理的勾选状态一目了然而且纯文本备份下来也不丢信息。2.4 引用、分隔线与转义字符引用用开头可以嵌套比如是外层是内层。引用块里可以放多个段落只要每个段落前都加就行。我写博客的时候经常用引用块放注意提示这类文字视觉上跟正文区分得很清楚。分隔线是三个及以上的-、*或_单独占一行。比如---或者***。这里有一个大坑如果上一行是文字再写---会被误认为二级标题。因为 Markdown 里文字加下划线恰好是标题的另一种写法。所以写分隔线之前一定要确保上面空一行。我自己的习惯是统一用---并且上下都留空行出错概率最低。转义字符可能很多人不知道但它关键时刻救命。Markdown 里有些字符是有特殊含义的比如*、#、、[你想在文档里直接显示这些符号前面加一个反斜杠\就行\*就能显示一个星号。我在写 Markdown 语法教学文档时这一招是必须掌握的不然没法在文章里展示语法本身。2.5 插入代码行内代码与代码块写技术文档的人几乎每篇都会用到代码。行内代码用一对反引号包起来比如print(hello)适合在正文里提及某个函数名或命令。多行代码则用代码块标准写法是三个反引号包起来并在开头标注语言python def hello(): print(Markdown 基础语法) 语言标注非常重要。它有两个作用一是让渲染器做语法高亮二是让某些平台比如 GitHub在代码块右上角显示复制按钮。常见的标注有python、bash、javascript、html、css、c、typescript等。如果你不确定代码语言也可以不标注但高亮就没了。另一种代码块写法是每行开头缩进四个空格但这种方式不好维护我基本不用只在一些老旧的论坛系统里才会碰到。缩进式代码块有个坑列表项里的代码块如果不额外缩进层级就会乱新手很容易在这里耗半天。2.6 链接与图片路径问题是重灾区链接的语法是[显示文字](地址)图片的语法是核心区别就是前面多了一个英文感叹号。替代文字很重要图片加载失败时它就是占位符屏幕阅读器也会读取它。图片路径是 Markdown 新手问得最多的问题之一。路径分两种网络 URL 和本地相对路径。写博客时用网络 URL 没问题但本地笔记里如果乱写路径换一台电脑或者移动文件后图片就全裂了。我的建议是图片跟文档放在同一个目录下引用时直接写文件名比如如果放在子目录里用相对路径比如绝对路径尽量别用C:\Users\xxx\图片.png这种一旦换机器必挂而且 Windows 路径里的反斜杠在 Markdown 里还有转义问题很容易踩坑。注意路径里的空格要用%20或者调整目录命名习惯。最好的办法是图片文件名从头到尾只用小写字母、数字、连字符、下划线空格和中文名统一规避能省掉大量莫名其妙的错误。2.7 表格写法与复制粘贴陷阱Markdown 表格的语法基础是三部分表头、分隔行、数据行。分隔行由|和-组成还可以用冒号控制对齐方式。| 功能 | 语法 | 说明 | | ---- | ---- | ---- | | 粗体 | **文字** | 加粗强调 | | 斜体 | *文字* | 倾斜强调 | | 删除线 | ~~文字~~ | 划线删除 |表格看起来简单实际操作时痛点不少。首先单元格里如果包含|字符需要用反斜杠转义为\|否则表格结构会直接坏掉。其次在手机上编辑表格特别痛苦因为竖线不好打。我的解决办法是先找一个在线表格转 Markdown 的小工具把 Excel 或 WPS 里的数据粘贴进去自动生成格式再粘回笔记里。还有一个高频场景Markdown 表格复制到 Excel 会乱。这个问题我后面在常见问题部分会专门讲这里先记住一个结论表格要转 Excel先转成 CSV再用 Excel 打开 CSV格式不会乱。3. 从基础到进阶的实用工作流3.1 选工具Markdown 编辑器与阅读器学完语法之后第一个现实问题就是用什么东西写、用什么打开.md文件。如果文件打不开一切白搭。先说明一个概念Markdown 本质是纯文本所以记事本、Sublime Text、VS Code 都能打开.md文件看到的都是带标记的原始文本。但想要看到渲染后的效果就需要专门的工具。我按使用场景分三类推荐本地写作首选Typora。所见即所得写完就渲染好了界面干净对新手极友好。需要付费但确实值。程序员熟悉 VS Code装一个 Markdown Preview Enhanced 插件或者直接在CtrlShiftV预览基本够用。Sublime Text 也可以装 MarkdownEditing 和 MarkdownPreview 插件来查看快捷键生成预览。知识管理用户选 Obsidian双链笔记、插件体系成熟本地文件夹管理非常适合长期积累笔记。Linux 环境下如果不想装图形界面程序命令行里有glow、mdless这类终端 Markdown 阅读器直接用glow README.md就能在终端里看到排版后的效果写服务器文档时很方便。如果你是纯新手不知道 Markdown 编辑器怎么下载安装我的建议是最简单的方式先装 VS Code免费、跨平台、插件丰富以后写代码还能接着用。微信、知乎这类平台自带的编辑器一般也支持基础语法可以先拿它们练手。3.2 数学公式用 LaTeX 语法插入公式很多写技术笔记、论文草稿、学习记录的人会遇到一个需求Markdown 里怎么插入数学公式其实 Markdown 本身不包含公式语法靠的是外部渲染引擎支持 LaTeX 风格的数学公式代码。常用的方式有两种行内公式用$...$包裹比如$Emc^2$块级公式用$$...$$包裹公式单独占一行并居中。行内公式示例质能方程 $Emc^2$。 块级公式示例 $$ e^{i\pi} 1 0 $$实际使用的时候Typora、Obsidian、VS Code 的 Markdown 插件都原生支持这些公式。有些平台支持不到位就需要借助 math 公式插件关键词通常是MathJax或KaTeX。它们的区别是KaTeX 更快MathJax 兼容性更好。如果你只是写简单公式KaTeX 足够如果涉及复杂推导选 MathJax 更稳。3.3 GitHub 的 Callout 和高级扩展如果你经常泡 GitHub会发现很多 README 里有那种带颜色的提示框看起来像引用块但左边有不同颜色的边框和图标。这种语法叫 Callout是 GitHub 对 Markdown 的扩展语法。写法是在引用块开头加一个标识符常用的是 [!NOTE] 普通提示信息。 [!TIP] 实用小技巧。 [!WARNING] 需要注意的风险。 [!CAUTION] 可能导致严重问题。这类语法的好处是信息层级特别清楚。我写项目 README 的时候安装步骤用 NOTE踩坑经验用 WARNING安全注意事项用 CAUTION读者扫一眼就能抓住重点。不过要注意Callout 只被部分平台识别如果你把文档发给不支持的人渲染出来也就是普通引用块不会报错内容还在。所以可以放心用。3.4 表格转 Excel、Markdown 转 Word 的实用路径工作中经常碰到这样的场景在 Markdown 里整理了一张表格同事非要 Excel 版本。还有的团队内部习惯了 Word 文档你写好的 Markdown 文档需要转成.docx发出去。先讲表格转 Excel。最快的方法分两步把 Markdown 表格粘贴到支持 CSV 导出的工具里或者直接手动整理成 CSV 格式用 Excel 打开 CSV 文件另存为.xlsx。如果表格特别多建议用 Pandoc 或者在线转换工具一步到位。Pandoc 的命令大致是pandoc input.md -o output.xlsx注意Pandoc 这里本质上也是先把表格提取出来再转换遇到复杂表格可能有样式丢失所以转完一定要抽查。再讲 Markdown 转 Word。这又是一个高频需求我自己的步骤是本地工具首选 Pandoc一个命令搞定pandoc README.md -o 输出.docxPandoc 能自动识别标题层级、代码块、表格、图片转换效果相当不错。没有安装 Pandoc 的话可以先用 Typora 的导出功能它自带 Word 选项只是对复杂样式的控制没 Pandoc 那么细。现在还有很多工作流平台支持自动化转换比如在 Coze 这类平台里搭一个Markdown 转 Word的工作流把文档丢进去自动生成 Word 再分发。适合需要大批量转换文档的团队场景。就我个人而言单次转换还是 Pandoc 最省心。3.5 把网页保存成干净的 Markdown经常会有这种需求看到一篇不错的网页文章想保存到自己的笔记库里。直接整个网页存下来又有一堆无关的导航、广告、推荐位抓取正文转成干净的 Markdown 才是最佳方案。这里推荐几个思路浏览器扩展搜索Save as Markdown或者Reader Mode这类扩展打开网页后一键保存大部分扩展会自动提取正文和图片。命令行工具很多开发者写的小工具能把网页正文提取成 Markdown配合 Python 脚本可以批量抓取保存。自动化工作流现在不少自动化助手都内置了网页转 Markdown的技能你只需要输入 URL它就能把网页正文整理成结构化的 md 文件。这类工具特别适合做信息收集和知识库沉淀。我自己保存网页文章的时候还会顺手处理一下图片把图片下载到本地同目录并把 Markdown 里的图片路径改成相对路径。这样就算原网页挂了我的笔记里图片也还在。另外如果你在用 Python 写爬虫脚本通常会先抓 HTML用 etree 或者类似方式解析网页里的某个 body 块再提取文本生成 Markdown。整个链路其实不复杂但最终输出的 Markdown 质量取决于你对正文区块的层级判断和清洗规则。建议保存后至少人工浏览一遍开头、代码块和图片区域确认没有多余杂质。4. 常见问题排查与避坑实录4.1 换行为什么不生效这是 Markdown 新手问得最多的问题没有之一。核心原因前面提过Markdown 的设计哲学是一个回车不换行空一行才是新段落。很多人在 Word 里养成了一行一回车的习惯到了 Markdown 里就觉得怎么都挤在一起。解决办法分场景同一段落内想换行行尾加两个空格再回车。想另起一段两行之间空一行。想强制换行且不加段落间距可以用br标签。我还要补充一种情况列表项内部的换行。如果想在列表项的下一行继续写文字但不想让它变成新的列表项需要在下一行开头补两个空格或按列表缩进对齐否则渲染器会认为你新开了一个列表项。4.2 图片显示不出来图片裂了十有八九是路径问题。排查顺序我一般是这样先确认图片文件真的在对应目录下文件名大小写对不对再看路径是绝对路径还是相对路径绝对路径在别的机器上必挂检查路径里有没有空格、中文、反斜杠最后看是不是网络图片被防盗链拦截如果是换成本地图片或者图床。如果用的是 Windows需要特别小心反斜杠\。Markdown 里反斜杠是转义符号所以你写C:\Users\name\pic.png时渲染器可能会把\U、\n这些组合当成转义字符路径就废了。正确写法是改用/C:/Users/name/pic.png或者在反斜杠前面再补一层转义。4.3 表格复制粘贴乱掉把 Markdown 里已经渲染好的表格直接复制到 Excel往往会变成一列、行错位、竖线乱蹦这是因为 Markdown 表格在渲染后没有真实的行列结构复制时 Excel 无法正确解析。稳妥的方法是先转 CSV。操作步骤把 Markdown 表格手动清理成 CSV 格式逗号分隔单元格换行分隔行如果单元格里有逗号用双引号包住整个单元格用 Excel 打开 CSV再另存为 xlsx。批量表格建议直接用 Pandoc 或者在线 Markdown 表格转换工具少受罪。4.4 代码块失灵或高亮不对代码块失灵通常有这几个原因三个反引号前后有空格或多余字符导致闭合失败语言标识写错比如把javascript写成js部分渲染器可能不支持代码块里嵌套代码块时内部的三个反引号没有用更多反引号包裹。我在写 Markdown 教学文章时常遇到嵌套的问题——要展示一个包含代码块的代码块最外层用四个反引号里层用三个markdown python print(嵌套示例) 看起来绕实际操作时这样处理就对了。4.5 问题排查速查表现象常见原因解决办法换行不生效单回车没有用行尾加两个空格或空一行分段标题不显示#后没空格#后加一个空格再写内容图片裂图路径错误或文件名不匹配用相对路径避免空格和中文表格复制到 Excel 乱格式不兼容先转 CSV 再用 Excel 打开粗体不生效用了下划线包裹统一改用**和*代码块不闭合反引号数量不匹配检查首尾反引号数量嵌套时外层多包一层分隔线变标题上一行没空行---上下方都留空行5. 写在最后的一点个人经验Markdown 学了不会亏这句话我这些年跟很多人说过现在依然这么认为。它不像编程语言那样需要系统的数据结构、算法基础也不像设计工具那样要研究视觉排版它就是一个纯文本搭配一套极简符号却能把你的写作效率实实在在地往上拉一截。我个人在实操中有两个习惯分享给你参考。第一把常用语法做成自己的速查表放在笔记软件里写完忘了就打开查一眼。用得多了自然熟根本不用死记。第二尽量把 Markdown 文件放在一个长期稳定的目录结构里图片统一放assets文件夹文件名保持规范这样等你的笔记积累到几千条的时候依然能游刃有余。还有一个扩展方向把 Markdown 作为输出格式接入自己的工作流比如用脚本批量生成周报、用网页转 Markdown 收藏资料、用 Pandoc 一键出 Word 版。等这些链路打通了你大概就跟我一样再也回不去 Word 手动排版的日子了。