我把Markdown语法从头到尾盘了一遍发现这东西远不是“几个井号和星号”那么简单。网上教程大多只讲个大概真到用的时候——换行不生效、表格复制到Excel乱成一团、图片显示不出来——又得四处翻资料。这篇文章就把这些坑一次性讲清楚以语法规则为主线把日常会碰到的所有标记整理成可以直接照抄的参考同时把换行、表格、图片路径、公式这些高频痛点单独拎出来说最后聊聊编辑器选型和排查技巧。不管你是刚开始接触md语法的新手还是已经用了几年但没系统整理过的人这篇都值得存一下。1. Markdown是什么为什么值得花时间系统整理1.1 从“语法总结”说起轻量标记语言的本质Markdown本质上是一套“给纯文本加排版规则”的约定。你用井号表示标题、星号表示加粗、横线表示列表写出来的文件本身是纯文本但放到支持的平台或编辑器里就会自动渲染成带层级的排版效果。说它是语法糖非常贴切——它把HTML标签封装成了更贴近自然输入的符号让你写文档的体验接近手写笔记而不是在Word里跟样式面板较劲。为什么这个看似简单的语法值得单独总结因为它的坑全藏在细节里。光是换行就有三种写法表格的分隔行少一个冒号对齐就失效图片路径带空格就直接挂掉。这些内容分散在各个教程的边角料里用的时候找不到找到了又不一定能看懂。把语法规则集中整理成一份笔记本身就是一件能长期复用的事无论写笔记、写博客、写项目README还是给公众号排版都能直接从这份总结里查答案。1.2 哪些人在用Markdown用在哪些场景Markdown的使用范围比想象中大得多。程序员写README和技术文档是最常见的场景GitHub、GitLab默认就把README渲染成排版好的页面写个人博客的人用它在静态博客框架里写文章比如Hexo、Hugo、VuePress这些工具的核心内容格式都是Markdown运营和内容编辑用它给公众号排版配合格式化工具可以快速做出整洁的图文学生和研究者用Markdown写实验报告、记课堂笔记再导出成PDF或Word交作业。笔记软件和办公协作工具也在全面拥抱这套语法。Obsidian、Typora、Notion、语雀、飞书文档都原生支持Markdown或提供兼容模式钉钉机器人发消息时也能用Markdown做预警卡片连思维导图工具都可以直接导入md文件生成结构图。生态覆盖得越广语法细节的差异就越明显同一份md文件在不同平台渲染结果不一样是常态。这也是我写这份总结的核心原因先搞懂标准语法再摸清各平台的脾气遇到问题才能快速定位是写错了还是平台不支持。2. 核心语法拆解从高频操作到易错细节2.1 标题、段落与换行最基础也最容易出错标题语法用井号实现一个#到六个#分别对应一级到六级标题写在行首后面要跟一个空格再接标题文字。很多人写##标题没加空格不同平台解析结果不一样——有的还能识别有的直接原样显示。标准写法是# 标题中间这个空格不能省这也是Markdown最容易忽略的基础规范。段落规则比大多数教程讲的更严格Markdown里换行不代表新段落空一行才算。我刚开始用Typora时写完一段直接按回车另起一行渲染出来两段文字连在一起当时还以为是软件坏了其实规则就是如此。真正的“换行”在Markdown里有三种做法一是在行尾加两个空格再回车这样渲染时会在下一行显示但两行仍然属于同一个段落二是直接空一行让两段文字彻底分开段落间距更大三是用HTML的br标签效果和两个空格一样。三种方式的应用场景完全不同写博客正文推荐空行分段写地址、写诗这类需要强制断行的内容用行尾两个空格在表格等特殊环境里用br更稳定。注意GitHub、知乎、公众号等平台对行尾两个空格的支持并不完全一致。如果发现换行在某个平台失效最稳妥的办法就是用空行分段别跟解析器较劲。2.2 强调、列表、引用与分割线排版基本功强调类语法分为斜体、粗体、删除线三种。斜体用一对星号*文字*或下划线_文字_包起来粗体用两对星号**文字**粗体加斜体用三对星号***文字***删除线用两对波浪线~~文字~~。注意星号两侧不要留空格** 文字 **会渲染成普通文本只有紧贴内容才生效。实际写作中重点术语用粗体轻微强调用斜体删除线主要用于标记废弃内容或玩笑语气不要滥用。列表分无序、有序和嵌套三种。无序列表用-、、*加空格开头有序列表用数字加英文句点加空格开头。不同符号混用在同一级列表里虽然能渲染成同一种样式但不推荐这么做统一用一种符号可读性更高。嵌套列表靠缩进控制二级列表要在父级列表下一行先缩进两个空格或一个Tab再接-三级以上依次增加缩进。这里有个很常见的坑有些平台要求缩进必须是四个空格或两个空格Tab在部分解析器里会失效最保险的做法是统一用四个空格缩进。引用用加空格开头可以嵌套多层会层层加深。引用块内的文字不解析标题语法但会解析粗体、斜体、列表等内联语法这点很多人不知道。分割线用三个及以上连续的-、*或_单独成行写成---即可。这里有个隐藏的坑必须提醒---在有些场景会被解析成上一级标题的“下划线式标题”比如前一行写了标题下一行紧跟---预览时它就成了二级标题。想避免误判在分割线前后各空一行基本能规避。2.3 链接、图片与图片路径的坑链接分行内式和参考式。行内式写法是[文字](地址)比如[Google](https://www.google.com)还可以加鼠标悬停提示[文字](地址 提示信息)。给链接增加标题属性后鼠标悬停时会出现提示文字写技术文档时很实用。参考式链接适合文档里多次引用同一地址的场景先在文中写[文字][引用名]再在文末统一定义[引用名]: https://example.com改链接只需改一处。图片语法和链接几乎一样只在前面多个感叹号。方括号里的文字是替代文本图片加载失败时会显示这段文字屏幕阅读器也会读取它所以别随便留空。图片路径是整个Markdown里最大的坑之一相对路径、绝对路径、网络URL、特殊字符、中文文件名、空格、括号任何一个处理不好图片就显示不出来。我处理图片路径的经验是本地项目里把图片统一放在assets或images文件夹中引用时写相对路径比如中文文件名在多数平台能渲染但为了兼容性还是改成英文或拼音更稳文件名带空格时要么用%20占位要么把整段路径放在尖括号内尖括号能应对空格和中文等特殊字符路径里如果有括号用反斜杠转义或同样包进尖括号。遇到过用OneNote Md Exporter导出笔记的情况它导出的图片默认放在同名文件夹下的media目录里路径用的是相对引用md文件一移动图片路径就全部失效导完就立刻改成本地图片链接或图床地址才能避免以后打开全是裂图。2.4 代码块、表格与任务列表行内代码用反引号包围比如git status适合在正文中标注命令、函数名、文件名等内容。代码块有两种写法缩进式和围栏式。缩进式是每行前面加四个空格或一个Tab语法简单但无法指定语言现在基本不用。推荐围栏式用三个反引号在代码块前后包裹在开头的三个反引号后面直接写语言名就可以高亮对应语言语法python def hello(): print(Hello, Markdown!) 这里的语言名非常关键。写Python就写python写Java写java写C写cpp或c写Shell写bash或shell正则表达式用regex。写错语言名最直接的影响是高亮失效代码变成纯文本但不会报错所以看起来“没反应”往往就是语言名写错了。除了反引号还可以用波浪线~~~包裹代码块效果相同但反引号更通用。表格语法是Markdown后期扩展的特性标准写法由表头、分隔行、内容行三部分组成| 功能 | 写法 | 说明 | | ---- | ---- | ---- | | 粗体 | **文字** | 常用 | | 斜体 | *文字* | 偶尔用 |分隔行里的:控制对齐方式默认左对齐写成:---:是居中对齐---:是右对齐。表格在渲染成HTML后本质是table所以单元格的内容不能跨行如果某个单元格需要多行文字只能塞入br。单元格里的竖线字符|需要转义写成\|否则会被当成列分隔符。表格最大的局限是窄屏下容易横向溢出手机端阅读体验很差所以表格内容尽量精简别堆长句子。任务列表是GitHub Flavored Markdown的扩展写法是- [ ] 待办事项和- [x] 已完成事项方括号里的空格表示未选中x表示选中。这个语法在GitHub、Typora、Obsidian中都支持但在部分旧平台会失效Unknown变成普通列表。3. 进阶能力公式、转换工作流与特殊场景3.1 数学公式与LaTeX语法Markdown原生不支持数学公式但主流编辑器通过插件扩展后可以在md文件里直接写LaTeX公式。行内公式用一对美元符号包围比如$E mc^2$块级公式用两对美元符号包围独占一行并居中显示。OpenAI等截图AI比较强但公式识别首推Mathpix它能直接截屏生成LaTeX代码再粘进Markdown。常用符号需要记一组上下标用^和_分数用\frac{分子}{分母}根号用\sqrt{}希腊字母用\alpha、\beta、\theta、\mu等求和符号是\sum_{i1}^{n}积分是\int_{a}^{b}。复杂一点的行内公式如果渲染异常可以拆成块级公式。要注意GitHub网页版默认不渲染$公式需要装浏览器插件或直接在Typora、VS Code的Markdown Preview Enhanced里查看在Typora里默认就是开启的在VS Code里需要在插件设置里启用数学渲染。3.2 表格快速转Excel与Markdown转Word“markdown表格转换excel”是热搜里出现频率很高的需求。直接在网页上复制一个Markdown表格再粘贴到Excel大概率会变成一列乱七八糟的文本因为Excel不认识竖线分隔符。正确的做法有两种。第一种用在线工具把Markdown表格转成CSV或TSV格式再打开Excel用“数据 - 自文本/CSV”导入指定分隔符为逗号或制表符就可以了。第二种本地用VS Code打开md文件选中表格内容用扩展把表格转成CSV再导入Excel。日常少量数据直接用在线转换器批量处理可以写一段脚本用pandoc转换。Markdown转Word用Pandoc是业界标准方案。在命令行执行pandoc input.md -o output.docx这条命令会用默认模板把Markdown转换为Word文档。如果要给Word加封面、调页边距、设字体pandoc自带的默认模板不够用更现实的做法是先用pandoc转出一个docx再在Word里手动调整样式反正大标题和正文结构已经分层了。还有人在Coze里搭“Markdown转Word”的工作流本质上也是调用pandoc或在线转换API适合处理批量文档但核心还是pandoc的转换能力。对普通用户来说一条命令就够了搭建工作流更多是为了自动化。3.3 思维导图、公众号格式化与钉钉预警消息思维导图也可以用Markdown生成。思路是先用多级无序列表写好大纲结构再用工具渲染。著名的markmap可以在浏览器里把Markdown列表渲染成思维导图VS Code里也有对应插件。XMind等桌面软件支持直接导入Markdown大纲文件。这种工作流的优点是大纲写在纯文本里编辑、版本控制、团队协作都很方便导图只是展示层。如果团队里有人不习惯导图直接看md大纲也能理解结构。公众号格式化是另一个典型场景。公众号后台编辑器对Markdown支持很差直接用md复制过去不会有排版效果。解决方案是用专门的格式化工具比较常见的是Md2All、doocs/md等把md内容粘贴进编辑器它会渲染成带样式的HTML再整体复制到公众号后台。操作流程是在左侧粘贴Markdown源码右侧实时预览调整主题配色和字号点击“复制到公众号”再到后台粘贴。需要提醒的是公众号格式化工具输出的样式带有内联CSS粘贴后如果修改字体字号最好在工具里统一设置而不是到后台逐段改。钉钉自定义机器人的自定义消息支持Markdown格式但这是一个“受限子集”实际不支持全部语法。一个典型的钉钉预警Markdown消息长这样## 系统异常告警 **服务名称**: 订单服务 **异常级别**: P1 **发生时间**: 2024-06-15 10:32:00 **错误信息**: 数据库连接超时 **处理建议**: 请立即检查数据库主备状态钉钉里支持标题、粗体、斜体、列表、链接等基础语法但表格、代码块、图片在某些客户端版本中支持不完整发预警时尽量用标题加粗列表的简单组合避免表格和复杂嵌套。这个经验对飞书、企业微信机器人同样适用它们的Markdown解析都是定制过的不能全信标准语法。3.4 PDF转Markdown与网页转Markdown和“Markdown转Word”相反的场景是从PDF反向提取Markdown。这个需求在整理文档资料时很常见PDF转Markdown的工具很多效果参差不齐。开源方案里Marker是做得比较好的一类能识别标题层级、列表、表格结构并输出大致可用的md文件公式较多的论文PDF用Mathpix识别效果更强。在线转换工具方便但要注意隐私敏感文档别往网页上传。网页转Markdown的需求也很高频用浏览器插件可以把文章正文一键提取成Markdown常见的是简悦、SpeedRead等。这类插件通过分析网页结构抓取正文去掉广告和导航再输出干净的文章。无论是网页转还是PDF转转换结果都需要人工检查一遍表格、代码、公式是重灾区尤其是PDF里多栏排版识别出来的顺序可能完全错乱。我的习惯是转换后先浏览一遍全文结构再看图片路径是否有效最后才使用。4. 工具选型与阅读方案4.1 主流编辑器对比Typora、VS Code、Obsidian、Notion怎么选编辑器选择直接影响写作体验。先看一张对比表编辑器价格实时预览扩展能力适用人群Typora付费买断优秀一般追求低干扰写作的笔记党和作者VS Code 插件免费优秀极强程序员和需要复杂扩展的人Obsidian免费优秀强本地笔记、知识管理重度用户Notion免费/订阅优秀中团队协作和在线文档Sublime 插件免费试用中等强习惯用Sublime的开发者用Typora的人很多它早期免费、界面简洁后来转向收费买断制说实话价格不算离谱但网上大量流传所谓“中文破解版”我不建议碰。一来安全没保障二来正版也支持持续更新直接支持开发者比自己折腾破解版踏实得多。不想付费的话VS Code加Markdown Preview Enhanced的组合是完全免费的替代方案功能更强只是配置成本略高。Obsidian适合把Markdown当知识库来管理的人它的双向链接和标签系统很有吸引力。Notion则把块编辑器和Markdown做了融合支持用/命令快速插入块严格来说不算是纯粹Markdown语法但日常写作足够。选编辑器不要贪多我的建议是本地纯写作首选Typora或Obsidian需要写代码和复杂排版选VS Code团队协作考虑Notion或语雀。4.2 编辑器插件与主题配置Markdown Preview Enhanced是VS Code里最值得装的扩展。装完后可以自定义预览样式、导出HTML/PDF/Word、支持数学公式、支持图表和流程图的Mermaid渲染、还可以把Markdown转成演示文稿。功能很全但容易踩的坑是导出PDF时中文字体问题直接在插件设置里把导出选项配置为“使用系统字体”能缓解。Sublime Text装Markdown插件也比较经典通过Package Control安装MarkdownEditing和MarkdownPreview前者提供语法高亮和自动缩进后者可以在浏览器里预览编译结果。再配一个LiveReload实现保存后自动刷新基本能达到接近Typora的使用体验。只是Sublime的实时预览比VS Code弱它走的是“浏览器刷新”路线需要联网或本地起一个预览服务。主题配置方面不管哪个编辑器都可以自定义CSS。Typora内置多套主题VS Code的MPE也支持自定义样式Obsidian的主题市场很丰富。我的建议是选一个浅色或深色主题固定下来字体用等宽字体写代码块正文字体用你日常办公的字体别频繁换主题写作工具的稳定性比新鲜感重要。4.3 .markdown文件怎么打开阅读器与在线预览方案README.md、.markdown这类文件本质是纯文本用系统自带的记事本就能打开但只能看到原始语法没有渲染效果。日常阅读推荐几个方案桌面端用Typora或VS Code直接打开所见即所得浏览器插件可以实现在线预览GitHub的md文件在网页上直接渲染本地文件用Markdown Viewer等浏览器插件可以双击后在浏览器里查看手机上阅读安卓推荐MarkoriOS可以用MWeb或直接用支持Markdown的笔记App。在线解析也可以把文件内容粘到Dillinger等在线编辑器里左侧源码右侧预览适合临时查看。图片较多的md文件比如OneNote导出的带图片笔记建议先检查图片路径是否有效再打开阅读否则预览里全是裂图。这个方向多看几次后面会少很多“打不开就烦躁”的体验。5. 常见问题与排查技巧实录5.1 表格相关的兼容性问题表格复制到Excel那件事很多人反复踩。先说现象直接复制表格粘贴到Excel数据全挤在第一列。原因是Excel粘贴时没有把|识别为列分隔符。解决方法有两个稳定路线一是先把表格转成TSV用Excel的“数据 - 自文本/CSV”导入导入向导里选“分隔符号”为制表符二是在线转换器转成CSV后再导入。Excel能正确识别CSV的逗号分隔基本不会乱。预览时表格错位也是高频问题。检查顺序表头数量和内容行数量是否一致分隔行是否写了至少三个短横线对齐冒号是否写对了位置单元格里有没有没转义的竖线。排查时把表格简化到三行两列再逐步加内容基本能很快定位问题。我的一个细节习惯是表格里不用太长的句子提前想好列结构省得来回调整。5.2 图片不显示的排查路径图片不显示是Markdown使用中出现频率最高的问题没有之一。我总结了一套排查顺序照着走基本能自己解决先确认方括号里的描述和圆括号里的路径之间没有多余空格再确认路径指向的文件真实存在注意大小写Linux服务器和GitHub对大小写敏感文件名里有空格或中文时用尖括号包住路径相对路径的基准是“当前md文件所在目录”如果你引用了./img/a.png确认md文件和img文件夹在同一个目录下如果是图床图片检查是否防盗链如果是本地路径确认打开md文件的工具能读取本地文件权限。还有个隐蔽问题用Typora把图片粘贴进文档时它会自动复制图片到配置的目录并在引用处自动生成路径看起来没问题但迁移时整个目录一起拷走才行只拷md文件图片肯定丢。我建议一开始就建立“md文件 assets文件夹”的固定结构统一放图片别把图片埋在各层目录里迁移时一拷就全走。5.3 换行、缩进、特殊字符与平台差异速查换行不生效的排查已经在前面讲过归纳成一句话想要段落分隔就空一行想要单行换行就用行尾两个空格或br。缩进问题在列表里最常见GitHub对列表缩进要求是四个空格但你用Tab也不会报错只是在不同平台间会有细微差别比如Typora里Tab能正常工作粘贴到部分在线Markdown编辑器就乱了。我的建议是列表嵌套一律手敲四个空格别依赖Tab。特殊字符转义也是隐藏知识点。写标题遇到井号写普通文本遇到星号、反引号、斜杠、尖括号等字符需要用反斜杠\转义比如\#就会原样显示井号。这个规则和大多数编程语言类似但很多人不知道Markdown也有转义。不同平台对语法支持有差异我整理了一个速查语法GitHubTyporaObsidian钉钉机器人公众号工具标题/粗体/斜体/列表支持支持支持支持支持表格支持支持支持部分支持支持任务列表支持支持支持不支持支持行内/块级公式不支持支持支持不支持部分支持嵌入HTML支持支持支持不支持支持这张表解决了一大半“为什么我的写法在A平台有效在B平台就失效”的困惑。看到这里如果你只用过其中一个平台记下自己常用平台支持的子集就够了如果你经常跨平台迁移文档尽量只用通用语法。最后再分享一个我实际用了很久的习惯在笔记里维护一个“语法模板文件”把上面这些标题、列表、表格、代码块、图片、引用、公式的常见用法全部写成示例每一行标注用途。新建笔记时复制这个模板再改内容遇到不确定的语法就打开模板看一眼。这比记忆所有规则轻松得多也把语法总结的价值落到了实处。 
长河君 · 2026/10/14 5:50:16 · 阅读 1.2k Markdown语法全解析：换行、表格、图片路径等高频坑位避坑指南
我把Markdown语法从头到尾盘了一遍发现这东西远不是“几个井号和星号”那么简单。网上教程大多只讲个大概真到用的时候——换行不生效、表格复制到Excel乱成一团、图片显示不出来——又得四处翻资料。这篇文章就把这些坑一次性讲清楚以语法规则为主线把日常会碰到的所有标记整理成可以直接照抄的参考同时把换行、表格、图片路径、公式这些高频痛点单独拎出来说最后聊聊编辑器选型和排查技巧。不管你是刚开始接触md语法的新手还是已经用了几年但没系统整理过的人这篇都值得存一下。1. Markdown是什么为什么值得花时间系统整理1.1 从“语法总结”说起轻量标记语言的本质Markdown本质上是一套“给纯文本加排版规则”的约定。你用井号表示标题、星号表示加粗、横线表示列表写出来的文件本身是纯文本但放到支持的平台或编辑器里就会自动渲染成带层级的排版效果。说它是语法糖非常贴切——它把HTML标签封装成了更贴近自然输入的符号让你写文档的体验接近手写笔记而不是在Word里跟样式面板较劲。为什么这个看似简单的语法值得单独总结因为它的坑全藏在细节里。光是换行就有三种写法表格的分隔行少一个冒号对齐就失效图片路径带空格就直接挂掉。这些内容分散在各个教程的边角料里用的时候找不到找到了又不一定能看懂。把语法规则集中整理成一份笔记本身就是一件能长期复用的事无论写笔记、写博客、写项目README还是给公众号排版都能直接从这份总结里查答案。1.2 哪些人在用Markdown用在哪些场景Markdown的使用范围比想象中大得多。程序员写README和技术文档是最常见的场景GitHub、GitLab默认就把README渲染成排版好的页面写个人博客的人用它在静态博客框架里写文章比如Hexo、Hugo、VuePress这些工具的核心内容格式都是Markdown运营和内容编辑用它给公众号排版配合格式化工具可以快速做出整洁的图文学生和研究者用Markdown写实验报告、记课堂笔记再导出成PDF或Word交作业。笔记软件和办公协作工具也在全面拥抱这套语法。Obsidian、Typora、Notion、语雀、飞书文档都原生支持Markdown或提供兼容模式钉钉机器人发消息时也能用Markdown做预警卡片连思维导图工具都可以直接导入md文件生成结构图。生态覆盖得越广语法细节的差异就越明显同一份md文件在不同平台渲染结果不一样是常态。这也是我写这份总结的核心原因先搞懂标准语法再摸清各平台的脾气遇到问题才能快速定位是写错了还是平台不支持。2. 核心语法拆解从高频操作到易错细节2.1 标题、段落与换行最基础也最容易出错标题语法用井号实现一个#到六个#分别对应一级到六级标题写在行首后面要跟一个空格再接标题文字。很多人写##标题没加空格不同平台解析结果不一样——有的还能识别有的直接原样显示。标准写法是# 标题中间这个空格不能省这也是Markdown最容易忽略的基础规范。段落规则比大多数教程讲的更严格Markdown里换行不代表新段落空一行才算。我刚开始用Typora时写完一段直接按回车另起一行渲染出来两段文字连在一起当时还以为是软件坏了其实规则就是如此。真正的“换行”在Markdown里有三种做法一是在行尾加两个空格再回车这样渲染时会在下一行显示但两行仍然属于同一个段落二是直接空一行让两段文字彻底分开段落间距更大三是用HTML的br标签效果和两个空格一样。三种方式的应用场景完全不同写博客正文推荐空行分段写地址、写诗这类需要强制断行的内容用行尾两个空格在表格等特殊环境里用br更稳定。注意GitHub、知乎、公众号等平台对行尾两个空格的支持并不完全一致。如果发现换行在某个平台失效最稳妥的办法就是用空行分段别跟解析器较劲。2.2 强调、列表、引用与分割线排版基本功强调类语法分为斜体、粗体、删除线三种。斜体用一对星号*文字*或下划线_文字_包起来粗体用两对星号**文字**粗体加斜体用三对星号***文字***删除线用两对波浪线~~文字~~。注意星号两侧不要留空格** 文字 **会渲染成普通文本只有紧贴内容才生效。实际写作中重点术语用粗体轻微强调用斜体删除线主要用于标记废弃内容或玩笑语气不要滥用。列表分无序、有序和嵌套三种。无序列表用-、、*加空格开头有序列表用数字加英文句点加空格开头。不同符号混用在同一级列表里虽然能渲染成同一种样式但不推荐这么做统一用一种符号可读性更高。嵌套列表靠缩进控制二级列表要在父级列表下一行先缩进两个空格或一个Tab再接-三级以上依次增加缩进。这里有个很常见的坑有些平台要求缩进必须是四个空格或两个空格Tab在部分解析器里会失效最保险的做法是统一用四个空格缩进。引用用加空格开头可以嵌套多层会层层加深。引用块内的文字不解析标题语法但会解析粗体、斜体、列表等内联语法这点很多人不知道。分割线用三个及以上连续的-、*或_单独成行写成---即可。这里有个隐藏的坑必须提醒---在有些场景会被解析成上一级标题的“下划线式标题”比如前一行写了标题下一行紧跟---预览时它就成了二级标题。想避免误判在分割线前后各空一行基本能规避。2.3 链接、图片与图片路径的坑链接分行内式和参考式。行内式写法是[文字](地址)比如[Google](https://www.google.com)还可以加鼠标悬停提示[文字](地址 提示信息)。给链接增加标题属性后鼠标悬停时会出现提示文字写技术文档时很实用。参考式链接适合文档里多次引用同一地址的场景先在文中写[文字][引用名]再在文末统一定义[引用名]: https://example.com改链接只需改一处。图片语法和链接几乎一样只在前面多个感叹号。方括号里的文字是替代文本图片加载失败时会显示这段文字屏幕阅读器也会读取它所以别随便留空。图片路径是整个Markdown里最大的坑之一相对路径、绝对路径、网络URL、特殊字符、中文文件名、空格、括号任何一个处理不好图片就显示不出来。我处理图片路径的经验是本地项目里把图片统一放在assets或images文件夹中引用时写相对路径比如中文文件名在多数平台能渲染但为了兼容性还是改成英文或拼音更稳文件名带空格时要么用%20占位要么把整段路径放在尖括号内尖括号能应对空格和中文等特殊字符路径里如果有括号用反斜杠转义或同样包进尖括号。遇到过用OneNote Md Exporter导出笔记的情况它导出的图片默认放在同名文件夹下的media目录里路径用的是相对引用md文件一移动图片路径就全部失效导完就立刻改成本地图片链接或图床地址才能避免以后打开全是裂图。2.4 代码块、表格与任务列表行内代码用反引号包围比如git status适合在正文中标注命令、函数名、文件名等内容。代码块有两种写法缩进式和围栏式。缩进式是每行前面加四个空格或一个Tab语法简单但无法指定语言现在基本不用。推荐围栏式用三个反引号在代码块前后包裹在开头的三个反引号后面直接写语言名就可以高亮对应语言语法python def hello(): print(Hello, Markdown!) 这里的语言名非常关键。写Python就写python写Java写java写C写cpp或c写Shell写bash或shell正则表达式用regex。写错语言名最直接的影响是高亮失效代码变成纯文本但不会报错所以看起来“没反应”往往就是语言名写错了。除了反引号还可以用波浪线~~~包裹代码块效果相同但反引号更通用。表格语法是Markdown后期扩展的特性标准写法由表头、分隔行、内容行三部分组成| 功能 | 写法 | 说明 | | ---- | ---- | ---- | | 粗体 | **文字** | 常用 | | 斜体 | *文字* | 偶尔用 |分隔行里的:控制对齐方式默认左对齐写成:---:是居中对齐---:是右对齐。表格在渲染成HTML后本质是table所以单元格的内容不能跨行如果某个单元格需要多行文字只能塞入br。单元格里的竖线字符|需要转义写成\|否则会被当成列分隔符。表格最大的局限是窄屏下容易横向溢出手机端阅读体验很差所以表格内容尽量精简别堆长句子。任务列表是GitHub Flavored Markdown的扩展写法是- [ ] 待办事项和- [x] 已完成事项方括号里的空格表示未选中x表示选中。这个语法在GitHub、Typora、Obsidian中都支持但在部分旧平台会失效Unknown变成普通列表。3. 进阶能力公式、转换工作流与特殊场景3.1 数学公式与LaTeX语法Markdown原生不支持数学公式但主流编辑器通过插件扩展后可以在md文件里直接写LaTeX公式。行内公式用一对美元符号包围比如$E mc^2$块级公式用两对美元符号包围独占一行并居中显示。OpenAI等截图AI比较强但公式识别首推Mathpix它能直接截屏生成LaTeX代码再粘进Markdown。常用符号需要记一组上下标用^和_分数用\frac{分子}{分母}根号用\sqrt{}希腊字母用\alpha、\beta、\theta、\mu等求和符号是\sum_{i1}^{n}积分是\int_{a}^{b}。复杂一点的行内公式如果渲染异常可以拆成块级公式。要注意GitHub网页版默认不渲染$公式需要装浏览器插件或直接在Typora、VS Code的Markdown Preview Enhanced里查看在Typora里默认就是开启的在VS Code里需要在插件设置里启用数学渲染。3.2 表格快速转Excel与Markdown转Word“markdown表格转换excel”是热搜里出现频率很高的需求。直接在网页上复制一个Markdown表格再粘贴到Excel大概率会变成一列乱七八糟的文本因为Excel不认识竖线分隔符。正确的做法有两种。第一种用在线工具把Markdown表格转成CSV或TSV格式再打开Excel用“数据 - 自文本/CSV”导入指定分隔符为逗号或制表符就可以了。第二种本地用VS Code打开md文件选中表格内容用扩展把表格转成CSV再导入Excel。日常少量数据直接用在线转换器批量处理可以写一段脚本用pandoc转换。Markdown转Word用Pandoc是业界标准方案。在命令行执行pandoc input.md -o output.docx这条命令会用默认模板把Markdown转换为Word文档。如果要给Word加封面、调页边距、设字体pandoc自带的默认模板不够用更现实的做法是先用pandoc转出一个docx再在Word里手动调整样式反正大标题和正文结构已经分层了。还有人在Coze里搭“Markdown转Word”的工作流本质上也是调用pandoc或在线转换API适合处理批量文档但核心还是pandoc的转换能力。对普通用户来说一条命令就够了搭建工作流更多是为了自动化。3.3 思维导图、公众号格式化与钉钉预警消息思维导图也可以用Markdown生成。思路是先用多级无序列表写好大纲结构再用工具渲染。著名的markmap可以在浏览器里把Markdown列表渲染成思维导图VS Code里也有对应插件。XMind等桌面软件支持直接导入Markdown大纲文件。这种工作流的优点是大纲写在纯文本里编辑、版本控制、团队协作都很方便导图只是展示层。如果团队里有人不习惯导图直接看md大纲也能理解结构。公众号格式化是另一个典型场景。公众号后台编辑器对Markdown支持很差直接用md复制过去不会有排版效果。解决方案是用专门的格式化工具比较常见的是Md2All、doocs/md等把md内容粘贴进编辑器它会渲染成带样式的HTML再整体复制到公众号后台。操作流程是在左侧粘贴Markdown源码右侧实时预览调整主题配色和字号点击“复制到公众号”再到后台粘贴。需要提醒的是公众号格式化工具输出的样式带有内联CSS粘贴后如果修改字体字号最好在工具里统一设置而不是到后台逐段改。钉钉自定义机器人的自定义消息支持Markdown格式但这是一个“受限子集”实际不支持全部语法。一个典型的钉钉预警Markdown消息长这样## 系统异常告警 **服务名称**: 订单服务 **异常级别**: P1 **发生时间**: 2024-06-15 10:32:00 **错误信息**: 数据库连接超时 **处理建议**: 请立即检查数据库主备状态钉钉里支持标题、粗体、斜体、列表、链接等基础语法但表格、代码块、图片在某些客户端版本中支持不完整发预警时尽量用标题加粗列表的简单组合避免表格和复杂嵌套。这个经验对飞书、企业微信机器人同样适用它们的Markdown解析都是定制过的不能全信标准语法。3.4 PDF转Markdown与网页转Markdown和“Markdown转Word”相反的场景是从PDF反向提取Markdown。这个需求在整理文档资料时很常见PDF转Markdown的工具很多效果参差不齐。开源方案里Marker是做得比较好的一类能识别标题层级、列表、表格结构并输出大致可用的md文件公式较多的论文PDF用Mathpix识别效果更强。在线转换工具方便但要注意隐私敏感文档别往网页上传。网页转Markdown的需求也很高频用浏览器插件可以把文章正文一键提取成Markdown常见的是简悦、SpeedRead等。这类插件通过分析网页结构抓取正文去掉广告和导航再输出干净的文章。无论是网页转还是PDF转转换结果都需要人工检查一遍表格、代码、公式是重灾区尤其是PDF里多栏排版识别出来的顺序可能完全错乱。我的习惯是转换后先浏览一遍全文结构再看图片路径是否有效最后才使用。4. 工具选型与阅读方案4.1 主流编辑器对比Typora、VS Code、Obsidian、Notion怎么选编辑器选择直接影响写作体验。先看一张对比表编辑器价格实时预览扩展能力适用人群Typora付费买断优秀一般追求低干扰写作的笔记党和作者VS Code 插件免费优秀极强程序员和需要复杂扩展的人Obsidian免费优秀强本地笔记、知识管理重度用户Notion免费/订阅优秀中团队协作和在线文档Sublime 插件免费试用中等强习惯用Sublime的开发者用Typora的人很多它早期免费、界面简洁后来转向收费买断制说实话价格不算离谱但网上大量流传所谓“中文破解版”我不建议碰。一来安全没保障二来正版也支持持续更新直接支持开发者比自己折腾破解版踏实得多。不想付费的话VS Code加Markdown Preview Enhanced的组合是完全免费的替代方案功能更强只是配置成本略高。Obsidian适合把Markdown当知识库来管理的人它的双向链接和标签系统很有吸引力。Notion则把块编辑器和Markdown做了融合支持用/命令快速插入块严格来说不算是纯粹Markdown语法但日常写作足够。选编辑器不要贪多我的建议是本地纯写作首选Typora或Obsidian需要写代码和复杂排版选VS Code团队协作考虑Notion或语雀。4.2 编辑器插件与主题配置Markdown Preview Enhanced是VS Code里最值得装的扩展。装完后可以自定义预览样式、导出HTML/PDF/Word、支持数学公式、支持图表和流程图的Mermaid渲染、还可以把Markdown转成演示文稿。功能很全但容易踩的坑是导出PDF时中文字体问题直接在插件设置里把导出选项配置为“使用系统字体”能缓解。Sublime Text装Markdown插件也比较经典通过Package Control安装MarkdownEditing和MarkdownPreview前者提供语法高亮和自动缩进后者可以在浏览器里预览编译结果。再配一个LiveReload实现保存后自动刷新基本能达到接近Typora的使用体验。只是Sublime的实时预览比VS Code弱它走的是“浏览器刷新”路线需要联网或本地起一个预览服务。主题配置方面不管哪个编辑器都可以自定义CSS。Typora内置多套主题VS Code的MPE也支持自定义样式Obsidian的主题市场很丰富。我的建议是选一个浅色或深色主题固定下来字体用等宽字体写代码块正文字体用你日常办公的字体别频繁换主题写作工具的稳定性比新鲜感重要。4.3 .markdown文件怎么打开阅读器与在线预览方案README.md、.markdown这类文件本质是纯文本用系统自带的记事本就能打开但只能看到原始语法没有渲染效果。日常阅读推荐几个方案桌面端用Typora或VS Code直接打开所见即所得浏览器插件可以实现在线预览GitHub的md文件在网页上直接渲染本地文件用Markdown Viewer等浏览器插件可以双击后在浏览器里查看手机上阅读安卓推荐MarkoriOS可以用MWeb或直接用支持Markdown的笔记App。在线解析也可以把文件内容粘到Dillinger等在线编辑器里左侧源码右侧预览适合临时查看。图片较多的md文件比如OneNote导出的带图片笔记建议先检查图片路径是否有效再打开阅读否则预览里全是裂图。这个方向多看几次后面会少很多“打不开就烦躁”的体验。5. 常见问题与排查技巧实录5.1 表格相关的兼容性问题表格复制到Excel那件事很多人反复踩。先说现象直接复制表格粘贴到Excel数据全挤在第一列。原因是Excel粘贴时没有把|识别为列分隔符。解决方法有两个稳定路线一是先把表格转成TSV用Excel的“数据 - 自文本/CSV”导入导入向导里选“分隔符号”为制表符二是在线转换器转成CSV后再导入。Excel能正确识别CSV的逗号分隔基本不会乱。预览时表格错位也是高频问题。检查顺序表头数量和内容行数量是否一致分隔行是否写了至少三个短横线对齐冒号是否写对了位置单元格里有没有没转义的竖线。排查时把表格简化到三行两列再逐步加内容基本能很快定位问题。我的一个细节习惯是表格里不用太长的句子提前想好列结构省得来回调整。5.2 图片不显示的排查路径图片不显示是Markdown使用中出现频率最高的问题没有之一。我总结了一套排查顺序照着走基本能自己解决先确认方括号里的描述和圆括号里的路径之间没有多余空格再确认路径指向的文件真实存在注意大小写Linux服务器和GitHub对大小写敏感文件名里有空格或中文时用尖括号包住路径相对路径的基准是“当前md文件所在目录”如果你引用了./img/a.png确认md文件和img文件夹在同一个目录下如果是图床图片检查是否防盗链如果是本地路径确认打开md文件的工具能读取本地文件权限。还有个隐蔽问题用Typora把图片粘贴进文档时它会自动复制图片到配置的目录并在引用处自动生成路径看起来没问题但迁移时整个目录一起拷走才行只拷md文件图片肯定丢。我建议一开始就建立“md文件 assets文件夹”的固定结构统一放图片别把图片埋在各层目录里迁移时一拷就全走。5.3 换行、缩进、特殊字符与平台差异速查换行不生效的排查已经在前面讲过归纳成一句话想要段落分隔就空一行想要单行换行就用行尾两个空格或br。缩进问题在列表里最常见GitHub对列表缩进要求是四个空格但你用Tab也不会报错只是在不同平台间会有细微差别比如Typora里Tab能正常工作粘贴到部分在线Markdown编辑器就乱了。我的建议是列表嵌套一律手敲四个空格别依赖Tab。特殊字符转义也是隐藏知识点。写标题遇到井号写普通文本遇到星号、反引号、斜杠、尖括号等字符需要用反斜杠\转义比如\#就会原样显示井号。这个规则和大多数编程语言类似但很多人不知道Markdown也有转义。不同平台对语法支持有差异我整理了一个速查语法GitHubTyporaObsidian钉钉机器人公众号工具标题/粗体/斜体/列表支持支持支持支持支持表格支持支持支持部分支持支持任务列表支持支持支持不支持支持行内/块级公式不支持支持支持不支持部分支持嵌入HTML支持支持支持不支持支持这张表解决了一大半“为什么我的写法在A平台有效在B平台就失效”的困惑。看到这里如果你只用过其中一个平台记下自己常用平台支持的子集就够了如果你经常跨平台迁移文档尽量只用通用语法。最后再分享一个我实际用了很久的习惯在笔记里维护一个“语法模板文件”把上面这些标题、列表、表格、代码块、图片、引用、公式的常见用法全部写成示例每一行标注用途。新建笔记时复制这个模板再改内容遇到不确定的语法就打开模板看一眼。这比记忆所有规则轻松得多也把语法总结的价值落到了实处。