陆陆续续在CSDN上写了几百篇技术博客之后我最大的感受是Markdown这套语法看着简单真正到了CSDN的编辑器里总有一些跟标准语法不一样的地方。热搜词里常年挂着markdown换行markdown表格转换excelmarkdown图片路径这类问题说明大家不是不会写而是被平台差异卡住了。这篇文章就把CSDN上的Markdown语法完整梳理一遍——从基础语法到代码块、图片表格、数学公式再到我踩过的各种坑适合刚接触博客写作的新手也适合写了很久但没系统整理过的老手。文章里所有写法都是我在CSDN编辑器里实测过的你照着抄就能用。1. CSDN的Markdown编辑器先搞清楚它和标准Markdown的差别1.1 三种编写模式别用错了CSDN的创作中心里写文章时有富文本和Markdown两种主要模式博客设置后台还能指定默认编辑器。我强烈建议直接用Markdown模式。富文本模式看着所见即所得但实际上粘贴进来的内容会混入大量隐藏标签导出的内容几乎没法复用Markdown模式是纯文本写作格式是写出来的不是点出来的思路清晰迁移也方便。还有个很多人不知道的细节CSDN的Markdown编辑器不是某个开源项目的原封不动版本它是经过多次改造的渲染层用的是自己服务端的Markdown解析加HTML过滤。这意味着同一个md文件在GitHub、语雀、Typora、CSDN里显示可能不完全一样。这不是你写错了而是各平台对某些扩展语法、某些HTML标签的支持力度不同。搞懂这一点很多排版不一致的困惑就能少一半。1.2 它实际遵循哪套标准CSDN的Markdown大体上兼容CommonMark规范同时支持GitHub Flavored MarkdownGFM里的部分扩展比如表格、任务列表、删除线、围栏代码块。此外还接入了数学公式和流程图等高级扩展。我用一张表梳理一下支持范围方便对照语法类别标准MarkdownGFMCSDN实测标题、段落、强调、列表、引用支持支持支持图片、链接、行内代码支持支持支持表格、任务列表、删除线部分支持支持围栏代码块加语言标注支持支持支持数学公式不支持不支持支持流程图/时序图/类图不支持不支持支持TOC自动目录插件不支持支持直接混写HTML标签支持部分部分受限这张表的信息量在于你在CSDN上能用的语法池子其实比标准Markdown更大但直接混写HTML时会遇到过滤。比如说脚本标签、iframe这类内容会被清理这是出于安全考虑。知道了边界写文章心里就有底了。1.3 为什么我坚持在CSDN上用Markdown原因很简单可迁移性。Markdown是纯文本换了平台、换了工具内容不会被锁在某个私有格式里。CSDN后台的文章导出功能导出的就是Markdown源文件同一篇文章可以很顺畅地同步到其他平台。如果一开始用富文本写导出后是一堆乱七八糟的标签基本等于要重写一遍。所以无论你是刚接触博客写作的新手还是写了多年的老手都值得在CSDN上用Markdown模式写你的下一篇文章。2. 高频基础语法标题、段落、换行、强调、列表、引用2.1 标题层级从#到######标题写法是行首加#号加空格一共六级# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题在CSDN正文里一级标题通常不用写因为文章有独立的大标题正文用二级标题做章节三级标题做小节比较合适。有个容易踩的坑标题下面如果紧跟着一行---在某些解析器里会变成Setext样式的二级标题渲染结果可能不是你想要的。我的建议是统一只用#号方式写标题少用下划线方式省得排版出幺蛾子。2.2 段落与换行热搜词markdown换行的答案段落之间要用空行分隔这一点没什么争议。真正让人困惑的是段落内按一次回车到底算不算换行。严格按CommonMark规范单个回车是软换行渲染时会被当成空格处理两个或更多连续回车才会产生新段落。但CSDN的编辑器实测表现比较宽容你在段落里按一次回车预览时通常也会换行显示。问题出在导出这种依赖编辑器宽容度的换行导出到其他平台后可能就被合并成空格了。热搜里常年出现的markdown换行不生效大部分就是这么来的。想在任何平台都稳定换行只有两种可靠写法行末加两个空格再回车这是标准Markdown的硬换行语法。直接空一行让这段文字变成独立段落。如果想让两行变成两段用方案2如果只想让两行在同一段落里换行显示比如地址、诗句用方案1。一个实用原则跨平台复用的内容一律按标准来。2.3 强调、斜体与删除线**粗体** *斜体* ***粗斜体*** ~~删除线~~注意分隔符两侧不要留空格** 文字 **这种写法在CSDN很多时候不生效。删除线是GFM扩展CSDN支持写修订记录或者不建议这样做的说明时特别好用。2.4 列表与引用无序列表用-、*、开头加空格有序列表用1.、2.开头- 列表项一 - 列表项二 1. 第一步 2. 第二步嵌套列表通过缩进实现- 一级 - 二级 - 三级任务列表是GFM扩展在CSDN里渲染成可勾选的复选框- [ ] 待办事项 - [x] 已完成事项引用用开头可以多级嵌套 这是一段引用 这是嵌套引用引用块里可以继续写列表、粗体甚至代码块写代码块时建议用围栏式不要用缩进四空格否则在引用内容易解析失败。3. 代码块与行内代码写技术博客的命脉3.1 行内代码与反引号数量的规则正文里提到函数名、命令、字段名时用单个反引号包裹调用 printf 函数输出内容如果代码内容本身包含反引号外层就用双反引号内容里再包含双反引号就继续加。这个规则对所有围栏式语法都适用理解了外层数量大于内层就不容易出错。3.2 围栏代码块与语言标注代码块的标准写法是三个反引号开头、三个反引号结尾开头一行后面直接写语言名print(hello world)ls -la /var/logCSDN支持的语言标注非常全我常用的有python、bash、java、c、cpp、javascript、typescript、go、sql、json、xml、html、css、markdown。标注语言的好处是自动高亮。实测不标注语言时CSDN有时候会猜猜错了高亮怪异代码可读性大打折扣。所以我的经验是每个代码块都老老实实标注语言。3.3 代码块内嵌套代码块写教程时经常要在代码块里展示代码块怎么写也就是代码块里嵌套代码块。办法是外层用四个反引号python print(hello) 这个技巧写Markdown教程、贴配置示例时几乎天天用到。我见过很多人因为不知道这个只能贴截图其实一个四反引号就能解决。3.4 缩进式代码块了解即可不建议用标准Markdown还支持每行缩进四个空格生成代码块。CSDN上这个写法可用但有两个麻烦一是普通文本和列表之间切换时缩进数量稍微不对就解析错二是从别处复制带缩进的文本时容易被误判成代码块。我建议一律用围栏代码块缩进式只做了解。3.5 粘贴代码被篡改的处理在CSDN编辑器里粘贴代码偶尔会遇到特殊字符被改掉的情况比如变成amp;amp;、变成lt;。这通常不是Markdown语法问题而是经过了富文本粘贴或者浏览器插件处理。正确做法是先粘贴到无格式环境记事本、VS Code过渡一下再复制进CSDN的Markdown编辑器。已经出现HTML实体字符的话用查找替换把amp;还原成再提交。这个坑我踩过好几次后来一律走中转粘贴流程再也没有复发。4. 图片、链接与目录资源管理的实战细节4.1 图片插入的三种方式CSDN插入图片有三种常见途径用编辑器工具栏的插入图片按钮。直接粘贴截图到编辑框CSDN会自动上传到自己的图片服务器并在光标位置生成Markdown图片语法。手动写。我最推荐前两种因为CSDN会自动托管图片不存在本地路径别人看不到的问题。从其他平台复制文章时图片外链可能失效或者被防盗链这种情况记得重新上传一遍。4.2 图片路径与尺寸控制热搜词markdown图片路径值得专门说清楚Markdown里的图片路径只认URL不认本地磁盘路径。如果你写别人看到的一定是裂图。CSDN渲染服务端根本访问不到你的电脑文件所以发文章前图片必须走线上URL。图片尺寸控制方面Markdown本身没有原生语法但CSDN支持混写HTML标签img src图片URL width50%也支持这类参数控制居中。图片太大时我会先压缩或者用width属性控制显示宽度不然文章加载慢版面也被撑得很难看。4.3 链接的写法[链接文字](https://example.com) [带标题的链接](https://example.com 悬停提示文字)引用式链接适合长文档统一管理[参考文档][1] [1]: https://example.comCSDN对裸URL一般也会自动转成可点击链接需要强制显示为纯文字时可以用反引号包起来。4.4 目录与锚点CSDN支持用[TOC]在文章开头插入自动目录它会抓取各级标题生成跳转链接。长文一定要加我自己的文章只要超过五个二级标题就必加目录。有个小提醒[TOC]在部分设备的预览模式里可能不显示但发布后是正常的。别因为预览里没看到目录就删掉它发布出去再看一眼。5. 表格、数学公式与高级扩展语法5.1 表格语法对齐、竖线转义、换行表格是CSDN博客里使用率极高的语法基本结构| 列1 | 列2 | 列3 | | --- | --- | --- | | A | B | C |第二行是分隔行冒号的位置决定对齐方式:---左对齐---:右对齐:---:居中| 左对齐 | 居中 | 右对齐 | | :--- | :---: | ---: | | A1 | A2 | A3 |表格单元格里的竖线|是分隔符内容真的需要竖线时必须转义成\|。单元格内换行可以写br。5.2 表格复制/转换Excel的痛点热搜词markdown表格转换excel和markdown表格复制反映的是同一个困扰。CSDN预览页面里的Markdown表格鼠标选中复制后粘贴到Excel通常能保持单元格结构但反过来把Excel表格往CSDN编辑器里粘贴时情况很复杂——可能变成一张图片也可能变成一堆HTML表格代码而不是Markdown。如果你想要的是Excel内容转成Markdown表格正确路径是先在Excel里把数据复制成纯文本或导出CSV再用在线工具或VS Code插件把CSV转成Markdown表格最后粘贴到CSDN。反过来走CSDN表格复制到Excel这条路通常更顺畅。理解了Markdown表格本质上就是带竖线的纯文本很多转换问题就迎刃而解。5.3 数学公式CSDN的加分项CSDN的Markdown支持数学公式行内用单个美元符块级用双美元符行内公式$E mc^2$ 块级公式 $$ x \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$常用命令\frac{a}{b}分数\sqrt{x}根号^上标_下标\sum_{i1}^{n}求和\int_a^b积分\alpha、\beta等希腊字母如果公式显示为源码而非渲染结果多半是美元符数量写错或者公式内容里有解析不了的空格。尽量用常用宏冷门宏在CSDN上偶尔会翻车。5.4 流程图与其他扩展CSDN不仅支持Markdown原生语法还内嵌了流程图、时序图和Mermaid图表的支持能画状态图、甘特图、类图等。需要提醒的是这类图在CSDN上的渲染表现和GitHub不完全一致画复杂图之前先在本地工具里验证一遍简单图直接写就行。5.5 脚注CSDN支持脚注语法正文标注[^1]文末定义这句话需要补充来源[^1]。 [^1]: 这里是脚注内容。写技术文章想补充参考来源又不打断正文这个功能非常实用。6. 我在CSDN踩过的坑与排查方法6.1 换行不生效最常见的问题症状编辑时按了回车预览里两行却挤在一起。原因Markdown的段落规则就是空行分段或行尾加两空格换行单个回车在严格解析下会被当作空格合并。处理办法行尾补两个空格或者直接空一行。如果你发现CSDN预览里一个回车其实生效了但导出到其他平台却不生效说明你依赖的是编辑器自己的宽容行为建议回到标准写法。6.2 表格错乱竖线和反斜杠的恩怨症状表格单元格的内容里包含竖线比如a|b渲染后表格列数变多。处理给竖线加反斜杠转义成a\|b。如果内容本身有反斜杠也要转义成\\。另外还要检查分隔行的短横线是不是够三根、对齐冒号有没有放对位置这些小细节都会导致渲染异常。6.3 代码块被浏览器或插件篡改症状粘贴的代码里特殊符号变了样变成amp;amp;变成lt;。原因多数时候是经过了富文本粘贴或浏览器翻译插件。处理先粘贴到记事本或VS Code再复制进CSDN的Markdown编辑器。已经出现HTML实体字符的查找替换还原即可。6.4 图片裂图外链失效的经典场景症状发布后图片加载不出来。判断方式在浏览器单独打开图片URL能看但文章里加载不出多半是防盗链直接404就是链接失效。处理重新上传到CSDN图床。别抱侥幸心理外链图片今天能用不代表明天能用。6.5 从Word复制导致的脏格式症状从Word直接复制内容到Markdown编辑器出现大量空白、乱码、字号标签预览一团糟。处理先在Word里把内容复制到记事本过渡一遍再从记事本复制到CSDN。我的习惯是需要长期维护的内容一开始就直接在CSDN的Markdown编辑器里写不经过Word。6.6 发布前检查与一个自用小技巧每次发布前我都会在CSDN的预览模式里完整浏览一遍标题层级是否合理、代码高亮是否正确、图片是否全部加载、表格有没有撑破版面。预览没问题再点发布。长文章写作期间记得开启自动保存隔一段时间手动导出一次Markdown源文件这是成本最低的保险。最后分享一个我坚持很久的习惯在CSDN上单独发一篇Markdown语法自用速查的私密文章把常用片段和踩坑记录都放进去。以后写新文章直接打开那篇速查复制基础模板不用现查语法省时间也省脑子。