1. 行内代码与代码块先搞清楚你写的到底是哪种代码很多人以为 Markdown 的代码语法就是打三个反引号结果真到写技术文档、配置说明、公众号排版的时候一粘贴就露馅反引号失效、高亮乱七八糟、代码块里的内容被解析成标题或列表甚至整篇文章格式崩掉。这些问题的根源几乎都是同一个——没有分清行内代码inline code和块级代码fenced code block的使用场景也没有搞懂 Markdown 渲染器处理这两种代码的底层逻辑。先说行内代码。在一段普通文字里如果你想标记一个命令、一个文件名、一个函数名、一个报错信息就用单个反引号把它包起来比如 npm install。渲染出来是等宽字体背景稍微有点底色一眼就能看出这是代码。那什么时候用行内代码我的习惯是只要这个代码片段是嵌在正常句子里、长度不超过一行就用行内代码。比如在终端里执行 git status 看看工作区状态这比把命令单独拎出来放一个代码块要自然得多。真正需要读者停下来仔细看的、需要复制粘贴去执行的完整代码才值得放进代码块。而块级代码就是那套经典的围栏写法三个反引号开头写完代码三个反引号结尾。它被渲染成一个独立的代码区域有自己的背景色、等宽字体、横向滚动条部分编辑器还会在原样展示之外标注语言类型并做高亮。围栏又分两种风味反引号围栏和波浪线围栏。三个波浪线 ~~~ 也可以围住代码块在极少数场景下比反引号好用——当你需要在代码块里展示反引号时波浪线就能避开冲突。还有一类容易被忽略的是缩进代码块。在 Markdown 早期还没有围栏语法的时候缩进代码块是唯一的标准每行开头缩进4个空格或一个 Tab渲染起来也是代码块效果。但缩进代码块有个致命的局限——它不支持语言标注写死了就是纯文本没有高亮也没有复制按钮。而且一旦你前面的段落没有用空行隔开或者缩进量不对它会被吞进上一个段落里变成普通文本。现在真正常用 Markdown 的人基本都只写围栏代码块缩进代码块只在某些老旧的渲染器里还能见到遇到别人写的文档里有这玩意儿建议直接改成围栏语法。核心判断标准记死行内代码是句子里的代码块级代码是独立的代码区域。两者不能混用行内代码里塞一大段 JSON 会让整个段落变成一个横向滚动几乎滚不到底的巨型长条反之一句话里的 node server.js 单独拎出来放代码块又会让阅读节奏断掉读者被迫上下扫视。这个边界很多新人不重视但实际写文档时它是阅读体验的第一道关卡。1.1 反引号嵌套的真正规则行内代码有个几乎所有新手都会踩的坑想在代码里展示反引号结果整个渲染乱掉。比如我想写 这样一个 Markdown 行内代码片段如果直接用单反引号包住 渲染器会在第一个反引号处就开始匹配然后戛然而止留下一堆反引号残骸。解决办法很简单用双反引号包住单反引号。也就是 段内反引号 这样写渲染器会自动识别我外面用了两个反引号作为边界那中间的单反引号就不是边界。如果里面要展示两个反引号外面就用三个。规则就是外层反引号的数量必须大于内部连续反引号的最大数量。这个规则同样适用于围栏代码块只是围栏的最小单位从1变成了3。我在撰写 Markdown 教程时经常要展示 这个标记本身最稳妥的做法是用四个反引号做外层围栏里面放三个反引号的示例。这样读者看到的是 python 这样的字样而不是被直接解析成代码块。很多编辑器如 Typora 还会在你输入三个反引号后立刻进入代码块编辑状态想展示语法本身就要学会这种外层加一层的操作。1.2 行内代码里的特殊字符要不要转义有一段内容是你想原样展示给读者的小片段它可能包含星号、下划线、井号、方括号你会担心这些符号被 Markdown 解析掉。这里有个关键知识在行内代码内部Markdown 的标记字符不会被当成语法解析。也就是说 重点 会原样显示为 *重点*不会把重点两个字加粗。#标题 也不会变成标题而是显示为 #标题 这个字符串。这一点和代码块一样——代码块内部就是一个原样输出的保护区所有 Markdown 语法在里面都被暂时冻结除了围栏边界本身。但要注意这个冻结不完全彻底。行内代码里如果想显示真正的 HTML 标签片段比如 渲染器多数会按字面展示不会真的把它当 HTML 标签渲染。而代码块内部如果想展示 HTML 标签同样按字面处理。这一点很重要因为很多人在 Markdown 里写 XML、写 HTML 示例时担心div被页面吃掉实际上在代码块里写就是安全的。这里再补一个细节换行处理。行内代码理论上不应该换行除非包的是极长的一串命令但实际渲染中不同渲染器对行内代码内的空格和换行处理都不一样。有的会把连续空格压缩成一个有的会保留。多数 Markdown 规范要求在行内代码里保留你输入的空格但我去 GitHub 上测试过如果行内代码里有换行GFM 会把换行显示成一个空格这一点和普通文本里的换行行为一致。所以我写行内代码时从不让它内部换行要保持代码片段的完整行形态。2. 语言标注与高亮魔法代码块进阶实战围栏代码块写好了下一步是语言标注。三个反引号后面紧跟语言名比如 python、javascript、bash、html、json、sql、yaml渲染器就知道该用哪种语言的语法规则来做高亮。这里注意语言标识符不要带点、不要带引号、不要写成 .python 或 python直接裸写语言名就行主流渲染器都认识常见的这些标识。语言标注的意义绝不只是好看。它让代码块有了语义这可是关键高亮是语义的可视化表达。编辑器或者渲染器根据语言标识调用对应的语法规则把关键字、字符串、注释、函数名分别上色。一句不带语言标识的代码块是纯黑白的读者无法快速区分哪部分是注释、哪部分是字符串字面量、哪部分是报错的关键字。技术文档里代码块占了绝大部分篇幅如果没有高亮阅读速度会直线下降尤其在你要找某个函数定义或者某个配置字段的时候。有的扩展语法还支持在语言标识后加其他参数比如 python title示例.py 或 python linenums可以在某些编辑器里显示代码块标题和行号。但这些是扩展而不是标准不同渲染器支持度完全不同。Typora 支持 title 属性VS Code 预览则把它当未知语言处理。所以如果你写的 Markdown 要跨平台用语言标识后面最好什么都别跟让它去适配最基础的场景。2.1 不写语言标识的后果不写语言标识代码块照样渲染只是没有高亮。但有些渲染器会把无语言标注的代码块当成纯文本用等宽字体展示这就导致你在代码块里写的 shell 变量 $PATH、Python 的 f-string、JS 的反引号模板字符串全部被一字不差地显示出来没有任何特殊处理。这本身没问题可一旦代码里包含类似 HTML 的尖括号比如泛型写法或 JSX 标签无标注时有些渲染器会尝试做一次智能解析把看起来像 HTML 的部分渲染成真的 HTML。最常见的就是在无语言标注的代码块里写divHello/div某些编辑器特别是把 Markdown 安全过滤做得很弱的渲染时会把 div 当 HTML 标签解析导致内容变成不可见元素或样式错乱。规范上代码块内容应该原样输出但现实中不少渲染器并不严格遵守。这是我一直强调要写语言标注的另一个原因明确告诉渲染器这是代码别瞎猜否则渲染器就可能按自己的启发式逻辑瞎猜。2.2 语言标识写法速查表不同编辑器支持的别名不完全一致但通用的主流写法我列在下面这条建议收藏你想高亮的语言围栏语言标识说明Pythonpython / py两者都常见python 更规范JavaScriptjavascript / jsjs 是通用缩写TypeScripttypescript / ts部分老渲染器不识别 tsShell 脚本bash / sh / shellbash 覆盖范围最广HTMLhtml / markup部分编辑器只认 htmlCSScss通用JSONjson / json5json 即可SQLsql通用Javajava通用C / Cc / cppcpp 不要写成 c加号在某些渲染器里会炸Gogo通用Rustrust通用YAMLyaml / yml都认有一点容易踩坑语言标识的大小写。后端 C 的标识通常写成 cpp而不是 c因为部分渲染器对语言名里的加号支持不好遇到 c 时可能返回未知语言然后直接放弃高亮代码块就变成纯文本了。另外别把语言标识和文件名搞混写 App.js 是错的前面我已经说过了语言标识里不允许带点号和斜杠。2.3 高亮失效时怎么排查我自己调试多处渲染问题时总结过一套排查顺序先确认围栏本身有没有闭合三个反引号结尾是不是独立成行。我最常看到的问题就是结尾反引号后面跟了空格或者文字渲染器识别不到闭合边界整个代码块就破壁了。确认语言标识是否在第一个反引号后紧跟不能有多余空格再跟语言名。 python 和 python 在部分渲染器里效果一样但也有渲染器把 python当成一个带空格的语言名直接不认。确认语言名是否是渲染器识别的名字。Typora 支持的语言列表和 GitHub 的 Linguist 高亮列表不完全一致有些小众格式比如 .env、Dockerfile 没有标准语言标识高亮不生效是正常的。如果代码块内部有连续空行有些渲染器会把空行前的换行吃掉导致整体行数变少这是渲染器对代码块末尾空行的不同处理不是语法错误但翻页时容易引起困惑。3. 换行才是第一杀手从markdown换行热搜说起热搜词里居然有markdown换行这让我挺意外的但仔细想想也合理。绝大多数新手第一次用 Markdown 写的不是文档而是在聊天框、笔记软件、公众号后台里打了几行字敲了回车结果发现渲染出来没换行或者换错行了。问题出在 Markdown 的换行哲学和普通文本完全不同。Markdown 里默认情况下一行末尾敲一个回车在渲染结果里会被当成一个空格不是换行。要真正换行你得在段内末尾加两个空格再回车或者直接空一行开启新段落。这是从 HTML 继承来的逻辑HTML 里连续的空格和换行会被折叠成一个空格Markdown 为了兼容这种折叠行为默认也做了同样的处理。所以你会碰到这些场景在 Typora 里按回车光标跳到新行但导出 HTML 后发现两行文字之间没有换行连成了一句话。这是 Typora 的所见即所得模式掩盖了源码里的换行标记导出时才暴露问题。在 GitHub 的 README 里写多行命令提示每行末尾加两个空格否则发布后变成一行冗长的文本。在聊天软件里用 Markdown 发多条消息换行处理规则还不一样有的平台自动把单回车转成换行有的不转于是各种为什么我换行没生效的抱怨铺天盖地。我个人强烈建议写 Markdown 时不要纠结软换行行尾两个空格直接养成用空行分段的习惯。空行分隔出来的段落是天然换行的语义清晰不会因为渲染器对行尾空格处理不同而出错。软换行在某些渲染器里会被忽略即使你在行尾打了两个空格遇到的平台如果用了 CommonMark 以外的解析规则也可能当成普通空格处理。空行是标准里最稳定的换行边界。3.1 代码块内部的换行为什么不会出问题代码块的规则和普通段落恰恰相反代码块内部的每次换行都会被严格保留。这是因为代码块的语义是按原样展示渲染器会把代码块内的换行符原封不动地传给输出不会折叠成空格。这个反差让很多人困惑普通文本里敲回车没用代码块里敲回车就一定有用答案是肯定的原因就是普通文本的换行折叠规则不适用于代码块。这也意味着如果你有一份需要保留换行的文本比如一段命令序列、一份配置文件、一个日志输出把它包进代码块里换行就安全了。但这里有个衍生问题很多人为了让普通文本换行把所有内容都塞进代码块结果是整篇文章变成一段又一段的灰色代码块完全丧失了 Markdown 的语义。这是最常见的滥用代码块之一。正确的做法是普通正文用空行分段把真正需要保留格式的命令、配置、日志才放进代码块。3.2 行尾两个空格与反斜杠换行的兼容性CommonMark 标准规定行尾加两个空格可以强制软换行softbreak行尾加反斜杠 \ 也可以。GitHub Flavored Markdown 同样支持这两种做法Typora 里按 ShiftEnter 会插入软换行标记。不同渲染器对这些细节的实现多数一致但还是有例外。我自己实测过在部分移动端 Markdown 编辑器里行尾空格会被自动清理你怎么打两个空格保存完再看空格没了软换行自然也就失效了。反斜杠换行在有些编辑器里会被智能移除认为你多打了一个转义符。所以如果你写的文档要长期保存并在多个平台使用请不要依赖行尾空格和反斜杠换行一律用空行分段。只有那些你已经锁定单一平台的写作场景比如只在 Typora 里写、只在 Typora 里看才可以用 ShiftEnter 制造漂亮的短行效果。3.3 代码块中的空行会不会被折叠代码块内部连续空行大多数渲染器都会保留但有一种情况值得注意代码块最后一行后面如果留了空行代码块的结束围栏紧跟在空行之后有些渲染器会在代码块底部多显示一个空行或者少显示一个空行。这不是语法问题是不同渲染器对末尾空行的处理差异。我的经验是代码块结尾不留空白行最后一个有效代码字符之后直接换行再写结束围栏这是最干净、最不容易出问题的写法。4. 转义与嵌套边界在代码块里安全地展示代码写技术博客最常遇到的一个需求是教别人写 Markdown自己就得在 Markdown 里展示 Markdown。这个自指场景是很多人的噩梦你想展示三反引号围栏结果这段内容自己先被解析成了代码块文章整个乱掉。解决方案前面提过外层围栏数大于内层最大反引号数。要展示一个 python 开头的代码块示例你可以用四个反引号作为外层围栏python print(hello) 渲染出来的结果就是一段完整的、带围栏的 Markdown 代码块读者可以直接看到 python 和 这些原始字符。这个技巧我几乎每周都会用到写教程、写 README、写 changelog 都有需求。另一个常见陷阱是在代码块里展示 HTML 标签。前面提到过字符串内不需要转义尖括号但在某些对安全要求极高的渲染环境里代码块内的script标签可能会被过滤掉或触发警告。这种情况不多见但如果你在写面向 CMS 或论坛的文档建议明明可以避免就不用代码块展示 HTML改用实体字符 script 来绕开过滤。代价是读者看到的不是完整标签而是实体字符不够直观算是少数派场景的取舍。4.1 代码块里还能不能再嵌套代码块严格意义上Markdown 不支持代码块嵌套代码块。你可以在外层代码块里展示内层代码块的源码但渲染结果只会有外层一个代码块内层内容按原样输出。想实现代码块中有两个子块的可视化效果官方 Markdown 没有这个语法你得借助表格、引用块或其他扩展。我的建议是不要试图在标准 Markdown 里嵌套代码块把复杂结构拆成多个代码块之间用说明文字衔接。4.2 数学公式和代码块的爱恨情仇搜索热词里有markdown 数学符号markdown数学公式插件说明很多人会在笔记里写公式。数学公式和代码块有个容易混淆的边界有的渲染器用 $$...$$ 表示块级公式有的用 \[..\]跟代码块的围栏语法完全是两回事。如果你在代码块里写一段 LaTeX 公式比如一段需要展示给读者的推导过程它是不会被当成公式渲染的——代码块内的所有内容被冻结包括 $$ 标记。反过来如果你想在普通文字里写一个公式却用反引号把它包起来比如 Emc^2那它会被当成行内代码而不是行内公式字体变成等宽体不会按公式排版。这是一个非常常见的误用很多人想让公式显得独立就顺手用了代码块结果 LaTeX 语法全都没有生效。正确做法是区分场景要展示带高亮的代码用代码块要展示数学推导和公式用数学公式语法不要用代码块包公式。部分编辑器如 Typora 支持数学公式内嵌在段落中用 $...$ 行内写法这个和行内代码互斥同一内容只能二选一。4.3 代码块里有没有注释要不要写注释讨论到这里其实涉及一个文档写作习惯的问题代码块内部要不要写注释、写多少注释。我的看法是Markdown 代码块里的代码注释应该遵循代码本身的规范而不是 Markdown 的规范。代码块内部保留原样输出所以 Python 的 # 注释、JS 的 // 注释、HTML 的 注释都按源码处理不会被 Markdown 误解析。很多新手以为在代码块里写 # 注释会被当成 Markdown 标题这是错觉——前面说过代码块是保护区井号在里面就是井号。所以放心写注释这是代码块可以放心的一个地方。真正建议少做的是在代码块内部用大量中文长句做注释因为代码块是等宽字体中文在其中的排版往往歪歪扭扭阅读体验不佳有耐心的建议把核心注释挪到代码块外部的正文里用 Markdown 的段落结构来解释。5. 编辑器渲染差异Typora、Obsidian 与 .md 文件打不开的问题聊完语法本身得说说现实世界的编辑器差异。这也是为什么很多人照着网上教程写代码语法换到另一个软件里效果全变了。Markdown 是标准但标准下的渲染器各有各的脾气了解这些差异能让你少掉很多头发。先说 Typora。它走的是所见即所得路线输入 Markdown 符号后立刻预览效果写代码块、改语言标注都是即时反馈。Typora 的背后有一个比较严格的解析器对空行的处理、对行尾空格的处理都偏向 CommonMark 的一致性所以 Typora 里排出来的效果拿到 GitHub 上多数不变形。它对数学公式、Mermaid 图表的支持也很完善这是很多技术博主选它的原因。但Typora 中文破解版这个热词让我有点警惕——Typora 在 1.0 之后转为付费软件网上流传的各种破解版绿色版鱼龙混杂有的版本里预置了可执行的广告脚本有的下载站把它捆绑了其他安装包。我的建议一直很简单写文档的工具最好用正规渠道的正版Typora 一次性买断价格并不高或者直接用免费的替代品完全没必要为此承担安全风险。再说 Obsidian。它是基于本地 Markdown 文件的笔记软件默认渲染偏向 CommonMark 一堆扩展插件代码高亮依赖 Prism 或 highlight.js换语言标识后高亮效果和 Typora 未必一致特别是 C、Rust 这类语言在不同高亮引擎里的效果差异很明显。Obsidian 的强项是双链和插件生态如果你主要在 Obsidian 里写笔记和知识管理那它就是你的主力环境语法测试以 Obsidian 的渲染为准。VS Code 是另一类。它的 Markdown 预览默认是 GitHub 风格的渲染规则接近 GFM但代码高亮依赖内置的 TextMate 语法库和 Typora 的高亮机制完全不同。VS Code 里写代码块遇到 edge case 时首先要意识到编辑器的语法高亮和预览渲染是两个不同的解析引擎编辑区里的颜色标识和预览区的颜色可能不一致。我见过不少人误会我明明写了语言标识为什么编辑区还是没高亮其实是编辑区把 Markdown 文件当成普通 Markdown 解析代码块的围栏语法识别到了但语言高亮要等预览才生效需要你装了对应的主题或插件才能同步。5.1 .md 文件怎么打开别再双击后面对记事本了.md 文件怎么打开能上热搜说明大量新手接触 Markdown 的第一个瓶颈不是语法而是工具链下载了一个 .md 文件双击弹出来的是记事本满屏都是井号和星号一下就没兴趣了。其实打开 .md 文件的方式非常多我列一下最实用的几条路径浏览器打开在 GitHub 仓库里直接点文件即可GitHub 会自动渲染 Markdown 为格式化文档。Typora / Obsidian 打开如果你已经装了编辑器右键 .md 文件选择打开方式或者直接拖到编辑器窗口里。VS Code 打开文件拖进 VS Code按 CtrlShiftV 打开预览面板立刻看渲染效果几乎零成本。命令行工具如果你在 WSL 或 Linux 终端里可以装一个 mdless、glow 之类的工具在终端里渲染查看适合快速浏览和脚本处理。这里有个建议如果你是重度 Markdown 用户给 .md 文件设置正确的默认打开方式通常我们会设置成 Typora 或 VS Code。这样下载文件、双击打开直接就进入渲染好的文档界面不会再有记事本看排版的糟糕体验。Windows 系统里文件右键属性可以修改默认程序macOS 里用显示简介修改打开方式这两步值得先做。5.2 图片路径问题为什么 md 文件换台电脑图片全挂图片路径是另一个高频热词——markdown图片路径、onenotemdexporter导出markdown图片路径不对。代码语法本身不涉及图片但 Markdown 文档里经常同时包含代码块和图片而图片路径的处理逻辑直接影响读者体验。Markdown 里插入图片的语法是 path 可以是相对路径也可以是绝对路径。相对路径比如 ./images/1.png它相对于当前 .md 文件所在的目录绝对路径比如 /assets/1.png它相对于网站的根目录或磁盘根目录。问题出在很多笔记软件会把你粘贴的图片自动存到一个隐藏的附件目录然后写进文档的却是相对路径或特殊协议路径。当你把 .md 文件单独发出去、或者移动到另一个目录时图片路径的基准变了图片自然就裂了。我的建议是如果写的是跨平台、可移植的 Markdown 文档图片统一用相对路径且图片要和 .md 文件放在同一个目录树的固定位置常见的做法是建立一个 images 目录文档里写 ./images/文件名.png。如果是在博客平台上发布直接上传图片得到 URL用绝对 URL 最可靠。用 Obsidian 的话可以设置附件默认存放路径到当前文档相同文件夹减少跨文件夹路径的困惑。另外一个隐藏技巧GitHub 的 README 图片尽量用 raw URL 或在仓库内相对路径尽量避免使用第三方图床链接防止图床失效后文档变盲文。5.3 复制与粘贴的隐秘差异markdown表格复制markdown表格转换excel这两个热词背后其实也隐藏着一个代码相关的问题当你把 Markdown 文档里的表格或代码块从一个平台复制到另一个平台时复制行为本身往往不等于你看到的渲染效果。以 Typora 为例复制一个代码块粘贴到聊天工具或 Word 里时大概率变成普通文本围栏符号和换行全都保留格式完全丢光。复制表格到 Excel 也一样Markdown 表格的管道分隔符不会被 Excel 自动识别为列分隔符你需要先转换成 CSV 或制表符分隔格式才能正确粘贴进表格。所以当你在多个平台之间搬运 Markdown 内容时要么用源码文本搬运粘贴到目标平台然后用目标平台的渲染器重新格式化要么用沉浸式导出比如 Typora 导出为 HTML 或 PDF 后再复制。不要期望跨工具复制能保留一切这是 Markdown 生态的固有摩擦不是语法问题。6. 代码语法在转换链路里的失真问题现实中Markdown 很少只停留在 Markdown 编辑器里它经常要转成 Word、转成 PDF、转成 HTML、甚至转成 Excel。每一次转换都是一次渲染器换人代码语法在这种转换链里是最容易失真的一环。热搜词里dify markdown转word中序号自动编号java word 转markdownpdf转markdownmarkdown表格转换excel集中反映了这个痛点。先说 Markdown 转 Word。最常用的工具是 Pandoc一行命令就能把 .md 转成 .docx。但 Pandoc 对代码块的处理有一个很多人不知道的细节默认情况下Pandoc 转换出的代码块在 Word 里不带高亮只保留等宽字体和底纹。要让 Word 里也带高亮你需要给 Pandoc 加 --syntax-highlighting 相关参数在 Pandoc 的选项里指定高亮风格。即便如此高亮效果和 Typora 里的效果仍然可能有色差因为 Word 对换页、行距、字体的处理方式和网页完全不同。转 Word 中序号自动编号这个现象更具体。有些工具在把 Markdown 转 Word 时代码块里如果有有序列表的写法比如 1. xxx转换器会把代码块的纯文本属性丢掉重新识别为 Word 的自动编号样式导出的文档里代码块数字字号错乱、缩进变化。这个问题的根因在于Markdown 代码块经过转换器时有些库比如一些 Java 侧的 md 转 docx 库没有正确处理代码块内的文本属性导致像列表、标题这类语义残留被带进了 Word 样式。解决方案不是改语法而是换工具用 Pandoc 转换时检查 --wrap 和偏移设置用专门支持代码块原样转出的转换器或者转完 Word 之后人工修复一次代码段样式。再说 PDF。Typora 导出 PDF 时代码块默认有背景色和边框行号可以被控制是否显示。但切到自定义主题时代码块字体大小、行高比例很容易脱离整体排版节奏导出的 PDF 里代码块与正文之间出现大块留白或者代码被截断。我遇到最多的是某行代码过长横向溢出PDF 直接把这行切断没有横向滚动条可以救。解决思路有两个一是把长代码在原文档里手工换行用反斜杠续行符二是导出前调整 PDF 的页面宽度和字体大小。从语法层面讲你无法强制 PDF 渲染器出现横向滚动所以长行在 PDF 场景下必须代码作者的换行意识来保证阅读体验。html 转 Markdown和PDF 转 Markdown则是另一个方向。从 HTML 或 PDF 转出来的 Markdown代码块经常被转成缩进代码块或带着大量内联样式语言标识丢失高亮全无。这类自动转换工具的产物我一般只作为初稿使用会手工重新整理代码块的围栏和语言标注。毕竟转换器可以识别这里有代码这个事实但它很难理解这段代码是什么语言、为什么它应该高亮。公众号文章markdown格式化又是一个热门方向。公众号后台自带的编辑器对 Markdown 支持为零你必须把 Markdown 排版成富文本。常见的做法是用 mdnice、doocs/md 这类在线工具把 Markdown 渲染成带样式的 HTML再粘贴到公众号编辑器。代码块是这里的重灾区很多在线工具渲染出的代码块是带内联样式的 div粘贴到公众号后代码块背景、边框、字体常常错乱。我自己的经验是公众号里的代码块尽量用短小片段长代码块粘贴后几乎都会出现样式失常而且公众号后台对行高、字间距的压缩会让长代码可读性很差。从这些转换场景里可以提炼出一个核心原则Markdown 的代码语法在标准渲染器里表现最稳定一旦进入像 Word、Excel、公众号后台这类非 Markdown 原生环境就必须接受样式折损。与其在转换后被重重问题纠缠不如在设计阶段就思考谁最终消费这份文档如果最终读者是在 Word 里过长的代码段应该提前拆行如果最终读者是在公众号代码块应该尽量短小精悍。这些经验都是代码语法之外的功夫但恰恰是最值钱的。6.1 代码块在转换中的元数据损失关于代码块转换还有一点值得专门提你的语言标识在转换中可能被丢弃也可能被错误映射成另一种语言。我试过用某些在线工具把包含 csharp 的 Markdown 转成 HTML结果代码块被渲染成 plaintext没有任何高亮。语言标识只是提示不是数据。这不是 Bug而是很多转换器对未知语言采取的保守策略认不出来的标识就按无高亮处理避免瞎高亮反而干扰阅读。所以代码块转没了颜色这类问题多数不是语法错误而是转换工具不支持该语言标识。解法很简单转成的结果里如果语言标识丢了那么转换前后都要检查一下高亮关键段是否完好。对技术写作者来说我的底线是重要文档转格式之前永远留一个 .md 源文件版本所有转换产物都是中间产物只有源文件是可长期维护的资产。6.2 用 Markdown 代码语法写非代码内容的技巧代码块不是只能放代码。我经常用代码块放配置文件、命令日志、目录树、甚至带格式的 ASCII 艺术图。代码块的最强特性就是保留原样把那种我想让读者原原本本看到的内容都往代码块里放可以让它在任何渲染器下都不变形。比如目录树写普通文本时树状结构的空格和对齐很容易被 Markdown 的段落折叠逻辑破坏。放进代码块后空格全部保留结构一目了然。再比如一段逻辑流程也可以做成代码块风格的无序列表用等宽字体展示层层嵌套。这其实是用代码块的语法来规避 Markdown 文本换行折叠的取巧方式很实用。要注意的就是代码块不是一个无样式容器它有自己的底色和边框用得多了文档会像大块矩阵所以每次用代码块装非代码内容时都问自己一次这段内容是否真的需要绝对保留原样如果只是想让排版好看应该用列表或引用块而不是代码块。7. 把 Markdown 当结构化语言用AI 提问场景下的代码输入最后一个热搜词很有意思——对deepseek提问是使用自然语言还是markdown更容易让ai明白指令。这问题从技术写作的角度看其实答案很清晰给 AI 的输入本身就是一份指令文档而 Markdown 的代码块正是为指令文档中的精确信息设计的。当你的提示词里包含一段 JSON、一段日志、一段配置文件、一段代码样例时如果直接以自然语言的形式塞进长对话里模型要自己从一整段散文式的描述里去猜哪部分是可执行代码、哪部分是你要修改的目标、哪部分是解释性文字。这不可避免会产生解析噪声——模型可能把注释当成指令、把代码当成描述、把描述当成代码。用代码块把这种精确数据包起来实际上等于告诉模型这里面是一个整体单元你按代码来理解不要混淆。我常用的做法是三层结构开头用自然语言描述任务背景和目标中间用代码块给出输入数据和期望输出格式末尾用简短的自然语言强调限制条件。这个结构与背景—输入—约束的指令设计模式高度一致而代码块恰好负责输入这一层让大段结构化数据不再与语言混在一起。特别是 JSON 类型的输入包进代码块后模型更容易感知到 JSON 结构的层级关系给出的应答也更贴合结构本身。还有一点关于 Mermaid。搜索词里markdown preview mermaid support反映出很多人在 Markdown 编辑器里写 Mermaid 图表代码结果预览区空白一片。Mermaid 不是 Markdown 的标准语法而是一个流行的图表扩展。Typora 原生支持 mermaid 代码块VS Code 需要装 Markdown Preview Mermaid Support 插件Obsidian 需要装社区插件。所以如果你写了 mermaid 代码块却没有预览先确认当前编辑器是不是安装了对应的 Mermaid 扩展这不是语法写错了是渲染环境没配对。AI 场景下的 Mermaid 也一样你可以让 AI 帮你生成 Mermaid 代码然后粘贴到支持 Mermaid 的编辑器里预览再迭代修改。这个流程本质上也是代码语法 渲染环境的配合底层逻辑和写 Markdown 代码块完全一致。7.1 提示词里代码块的边界控制用代码块给 AI 输入信息时边界控制比日常写作还要严格。因为模型会解析你的代码块如果代码块内外信息交叉嵌套模型反而会被绕晕。我总结出几条实践原则一个代码块只放一种类型的数据不要把 JSON 和 shell 命令混在一个块里。代码块内不要写大段解释性文字解释放代码块外代码块里只放数据本身。如果数据里本身包含三个反引号外层围栏记得用四个否则模型也会被误导以为围栏提前闭合。在代码块开头第一行写上数据格式提示比如 json 本身就是给模型看的格式提示引导它用 JSON 的逻辑处理内部内容。这些原则和写给人看的文档其实是相通的只是在 AI 场景里错误容忍度更低——给人类读者造成轻微困惑的歧义给模型可能直接导致输出结果完全跑偏。7.2 Markdown 代码语法与其他结构化语法的边界最后想理清一个容易混淆的概念Markdown 代码语法和代码片段管理工具或代码高亮库是两回事。Markdown 负责的是文本级的围栏标注它本身不执行代码、不编译不运行只是标记哪里是代码区域。实际的高亮动作由渲染器里的语法高亮引擎完成比如 highlight.js、Prism、Shiki这些库各有各的语言标识库覆盖范围。所以你在某个编辑器里写的 python 换到另一个编辑器可能高亮效果完全不同这不代表你写错了而是底层高亮引擎换了。同理某个代码块在网页上显示包含行号和复制按钮那是前端框架基于代码块语义做的增强不是 Markdown 语法本身的功能。理解这一层你就能更理性地看待为什么同样一份 Markdown 在不同的地方长不一样这个问题。诚实地讲Markdown 的代码语法在语法层面上真的非常简单算上所有细节也就几千字能讲完。真正复杂的是它所在的整个生态编辑器的差异、渲染器的差异、转换链路的差异、使用者习惯的差异。这也是为什么我说代码语法只是起点渲染生态才是真正的战场。你越早建立这种生态观越少在具体某个软件的渲染怪癖上浪费时间。我自己现在写任何技术文档对代码块的使用已经形成一套近乎固定的习惯短命令和文件名用行内代码完整可运行的片段用带语言标注的围栏代码块长代码块提前手工拆行避免转换截断不依赖行尾空格做软换行图片全部放进 images 目录用相对路径引用。这套习惯本身不复杂但它为我节省的调试时间非常多。如果你还在被明明写对了却渲染不对这类问题反复困扰不妨也给自己定一套类似的固定规矩越简单越好能自动化就自动化然后把多余精力留给内容本身。
1. 行内代码与代码块先搞清楚你写的到底是哪种代码很多人以为 Markdown 的代码语法就是打三个反引号结果真到写技术文档、配置说明、公众号排版的时候一粘贴就露馅反引号失效、高亮乱七八糟、代码块里的内容被解析成标题或列表甚至整篇文章格式崩掉。这些问题的根源几乎都是同一个——没有分清行内代码inline code和块级代码fenced code block的使用场景也没有搞懂 Markdown 渲染器处理这两种代码的底层逻辑。先说行内代码。在一段普通文字里如果你想标记一个命令、一个文件名、一个函数名、一个报错信息就用单个反引号把它包起来比如 npm install。渲染出来是等宽字体背景稍微有点底色一眼就能看出这是代码。那什么时候用行内代码我的习惯是只要这个代码片段是嵌在正常句子里、长度不超过一行就用行内代码。比如在终端里执行 git status 看看工作区状态这比把命令单独拎出来放一个代码块要自然得多。真正需要读者停下来仔细看的、需要复制粘贴去执行的完整代码才值得放进代码块。而块级代码就是那套经典的围栏写法三个反引号开头写完代码三个反引号结尾。它被渲染成一个独立的代码区域有自己的背景色、等宽字体、横向滚动条部分编辑器还会在原样展示之外标注语言类型并做高亮。围栏又分两种风味反引号围栏和波浪线围栏。三个波浪线 ~~~ 也可以围住代码块在极少数场景下比反引号好用——当你需要在代码块里展示反引号时波浪线就能避开冲突。还有一类容易被忽略的是缩进代码块。在 Markdown 早期还没有围栏语法的时候缩进代码块是唯一的标准每行开头缩进4个空格或一个 Tab渲染起来也是代码块效果。但缩进代码块有个致命的局限——它不支持语言标注写死了就是纯文本没有高亮也没有复制按钮。而且一旦你前面的段落没有用空行隔开或者缩进量不对它会被吞进上一个段落里变成普通文本。现在真正常用 Markdown 的人基本都只写围栏代码块缩进代码块只在某些老旧的渲染器里还能见到遇到别人写的文档里有这玩意儿建议直接改成围栏语法。核心判断标准记死行内代码是句子里的代码块级代码是独立的代码区域。两者不能混用行内代码里塞一大段 JSON 会让整个段落变成一个横向滚动几乎滚不到底的巨型长条反之一句话里的 node server.js 单独拎出来放代码块又会让阅读节奏断掉读者被迫上下扫视。这个边界很多新人不重视但实际写文档时它是阅读体验的第一道关卡。1.1 反引号嵌套的真正规则行内代码有个几乎所有新手都会踩的坑想在代码里展示反引号结果整个渲染乱掉。比如我想写 这样一个 Markdown 行内代码片段如果直接用单反引号包住 渲染器会在第一个反引号处就开始匹配然后戛然而止留下一堆反引号残骸。解决办法很简单用双反引号包住单反引号。也就是 段内反引号 这样写渲染器会自动识别我外面用了两个反引号作为边界那中间的单反引号就不是边界。如果里面要展示两个反引号外面就用三个。规则就是外层反引号的数量必须大于内部连续反引号的最大数量。这个规则同样适用于围栏代码块只是围栏的最小单位从1变成了3。我在撰写 Markdown 教程时经常要展示 这个标记本身最稳妥的做法是用四个反引号做外层围栏里面放三个反引号的示例。这样读者看到的是 python 这样的字样而不是被直接解析成代码块。很多编辑器如 Typora 还会在你输入三个反引号后立刻进入代码块编辑状态想展示语法本身就要学会这种外层加一层的操作。1.2 行内代码里的特殊字符要不要转义有一段内容是你想原样展示给读者的小片段它可能包含星号、下划线、井号、方括号你会担心这些符号被 Markdown 解析掉。这里有个关键知识在行内代码内部Markdown 的标记字符不会被当成语法解析。也就是说 重点 会原样显示为 *重点*不会把重点两个字加粗。#标题 也不会变成标题而是显示为 #标题 这个字符串。这一点和代码块一样——代码块内部就是一个原样输出的保护区所有 Markdown 语法在里面都被暂时冻结除了围栏边界本身。但要注意这个冻结不完全彻底。行内代码里如果想显示真正的 HTML 标签片段比如 渲染器多数会按字面展示不会真的把它当 HTML 标签渲染。而代码块内部如果想展示 HTML 标签同样按字面处理。这一点很重要因为很多人在 Markdown 里写 XML、写 HTML 示例时担心div被页面吃掉实际上在代码块里写就是安全的。这里再补一个细节换行处理。行内代码理论上不应该换行除非包的是极长的一串命令但实际渲染中不同渲染器对行内代码内的空格和换行处理都不一样。有的会把连续空格压缩成一个有的会保留。多数 Markdown 规范要求在行内代码里保留你输入的空格但我去 GitHub 上测试过如果行内代码里有换行GFM 会把换行显示成一个空格这一点和普通文本里的换行行为一致。所以我写行内代码时从不让它内部换行要保持代码片段的完整行形态。2. 语言标注与高亮魔法代码块进阶实战围栏代码块写好了下一步是语言标注。三个反引号后面紧跟语言名比如 python、javascript、bash、html、json、sql、yaml渲染器就知道该用哪种语言的语法规则来做高亮。这里注意语言标识符不要带点、不要带引号、不要写成 .python 或 python直接裸写语言名就行主流渲染器都认识常见的这些标识。语言标注的意义绝不只是好看。它让代码块有了语义这可是关键高亮是语义的可视化表达。编辑器或者渲染器根据语言标识调用对应的语法规则把关键字、字符串、注释、函数名分别上色。一句不带语言标识的代码块是纯黑白的读者无法快速区分哪部分是注释、哪部分是字符串字面量、哪部分是报错的关键字。技术文档里代码块占了绝大部分篇幅如果没有高亮阅读速度会直线下降尤其在你要找某个函数定义或者某个配置字段的时候。有的扩展语法还支持在语言标识后加其他参数比如 python title示例.py 或 python linenums可以在某些编辑器里显示代码块标题和行号。但这些是扩展而不是标准不同渲染器支持度完全不同。Typora 支持 title 属性VS Code 预览则把它当未知语言处理。所以如果你写的 Markdown 要跨平台用语言标识后面最好什么都别跟让它去适配最基础的场景。2.1 不写语言标识的后果不写语言标识代码块照样渲染只是没有高亮。但有些渲染器会把无语言标注的代码块当成纯文本用等宽字体展示这就导致你在代码块里写的 shell 变量 $PATH、Python 的 f-string、JS 的反引号模板字符串全部被一字不差地显示出来没有任何特殊处理。这本身没问题可一旦代码里包含类似 HTML 的尖括号比如泛型写法或 JSX 标签无标注时有些渲染器会尝试做一次智能解析把看起来像 HTML 的部分渲染成真的 HTML。最常见的就是在无语言标注的代码块里写divHello/div某些编辑器特别是把 Markdown 安全过滤做得很弱的渲染时会把 div 当 HTML 标签解析导致内容变成不可见元素或样式错乱。规范上代码块内容应该原样输出但现实中不少渲染器并不严格遵守。这是我一直强调要写语言标注的另一个原因明确告诉渲染器这是代码别瞎猜否则渲染器就可能按自己的启发式逻辑瞎猜。2.2 语言标识写法速查表不同编辑器支持的别名不完全一致但通用的主流写法我列在下面这条建议收藏你想高亮的语言围栏语言标识说明Pythonpython / py两者都常见python 更规范JavaScriptjavascript / jsjs 是通用缩写TypeScripttypescript / ts部分老渲染器不识别 tsShell 脚本bash / sh / shellbash 覆盖范围最广HTMLhtml / markup部分编辑器只认 htmlCSScss通用JSONjson / json5json 即可SQLsql通用Javajava通用C / Cc / cppcpp 不要写成 c加号在某些渲染器里会炸Gogo通用Rustrust通用YAMLyaml / yml都认有一点容易踩坑语言标识的大小写。后端 C 的标识通常写成 cpp而不是 c因为部分渲染器对语言名里的加号支持不好遇到 c 时可能返回未知语言然后直接放弃高亮代码块就变成纯文本了。另外别把语言标识和文件名搞混写 App.js 是错的前面我已经说过了语言标识里不允许带点号和斜杠。2.3 高亮失效时怎么排查我自己调试多处渲染问题时总结过一套排查顺序先确认围栏本身有没有闭合三个反引号结尾是不是独立成行。我最常看到的问题就是结尾反引号后面跟了空格或者文字渲染器识别不到闭合边界整个代码块就破壁了。确认语言标识是否在第一个反引号后紧跟不能有多余空格再跟语言名。 python 和 python 在部分渲染器里效果一样但也有渲染器把 python当成一个带空格的语言名直接不认。确认语言名是否是渲染器识别的名字。Typora 支持的语言列表和 GitHub 的 Linguist 高亮列表不完全一致有些小众格式比如 .env、Dockerfile 没有标准语言标识高亮不生效是正常的。如果代码块内部有连续空行有些渲染器会把空行前的换行吃掉导致整体行数变少这是渲染器对代码块末尾空行的不同处理不是语法错误但翻页时容易引起困惑。3. 换行才是第一杀手从markdown换行热搜说起热搜词里居然有markdown换行这让我挺意外的但仔细想想也合理。绝大多数新手第一次用 Markdown 写的不是文档而是在聊天框、笔记软件、公众号后台里打了几行字敲了回车结果发现渲染出来没换行或者换错行了。问题出在 Markdown 的换行哲学和普通文本完全不同。Markdown 里默认情况下一行末尾敲一个回车在渲染结果里会被当成一个空格不是换行。要真正换行你得在段内末尾加两个空格再回车或者直接空一行开启新段落。这是从 HTML 继承来的逻辑HTML 里连续的空格和换行会被折叠成一个空格Markdown 为了兼容这种折叠行为默认也做了同样的处理。所以你会碰到这些场景在 Typora 里按回车光标跳到新行但导出 HTML 后发现两行文字之间没有换行连成了一句话。这是 Typora 的所见即所得模式掩盖了源码里的换行标记导出时才暴露问题。在 GitHub 的 README 里写多行命令提示每行末尾加两个空格否则发布后变成一行冗长的文本。在聊天软件里用 Markdown 发多条消息换行处理规则还不一样有的平台自动把单回车转成换行有的不转于是各种为什么我换行没生效的抱怨铺天盖地。我个人强烈建议写 Markdown 时不要纠结软换行行尾两个空格直接养成用空行分段的习惯。空行分隔出来的段落是天然换行的语义清晰不会因为渲染器对行尾空格处理不同而出错。软换行在某些渲染器里会被忽略即使你在行尾打了两个空格遇到的平台如果用了 CommonMark 以外的解析规则也可能当成普通空格处理。空行是标准里最稳定的换行边界。3.1 代码块内部的换行为什么不会出问题代码块的规则和普通段落恰恰相反代码块内部的每次换行都会被严格保留。这是因为代码块的语义是按原样展示渲染器会把代码块内的换行符原封不动地传给输出不会折叠成空格。这个反差让很多人困惑普通文本里敲回车没用代码块里敲回车就一定有用答案是肯定的原因就是普通文本的换行折叠规则不适用于代码块。这也意味着如果你有一份需要保留换行的文本比如一段命令序列、一份配置文件、一个日志输出把它包进代码块里换行就安全了。但这里有个衍生问题很多人为了让普通文本换行把所有内容都塞进代码块结果是整篇文章变成一段又一段的灰色代码块完全丧失了 Markdown 的语义。这是最常见的滥用代码块之一。正确的做法是普通正文用空行分段把真正需要保留格式的命令、配置、日志才放进代码块。3.2 行尾两个空格与反斜杠换行的兼容性CommonMark 标准规定行尾加两个空格可以强制软换行softbreak行尾加反斜杠 \ 也可以。GitHub Flavored Markdown 同样支持这两种做法Typora 里按 ShiftEnter 会插入软换行标记。不同渲染器对这些细节的实现多数一致但还是有例外。我自己实测过在部分移动端 Markdown 编辑器里行尾空格会被自动清理你怎么打两个空格保存完再看空格没了软换行自然也就失效了。反斜杠换行在有些编辑器里会被智能移除认为你多打了一个转义符。所以如果你写的文档要长期保存并在多个平台使用请不要依赖行尾空格和反斜杠换行一律用空行分段。只有那些你已经锁定单一平台的写作场景比如只在 Typora 里写、只在 Typora 里看才可以用 ShiftEnter 制造漂亮的短行效果。3.3 代码块中的空行会不会被折叠代码块内部连续空行大多数渲染器都会保留但有一种情况值得注意代码块最后一行后面如果留了空行代码块的结束围栏紧跟在空行之后有些渲染器会在代码块底部多显示一个空行或者少显示一个空行。这不是语法问题是不同渲染器对末尾空行的处理差异。我的经验是代码块结尾不留空白行最后一个有效代码字符之后直接换行再写结束围栏这是最干净、最不容易出问题的写法。4. 转义与嵌套边界在代码块里安全地展示代码写技术博客最常遇到的一个需求是教别人写 Markdown自己就得在 Markdown 里展示 Markdown。这个自指场景是很多人的噩梦你想展示三反引号围栏结果这段内容自己先被解析成了代码块文章整个乱掉。解决方案前面提过外层围栏数大于内层最大反引号数。要展示一个 python 开头的代码块示例你可以用四个反引号作为外层围栏python print(hello) 渲染出来的结果就是一段完整的、带围栏的 Markdown 代码块读者可以直接看到 python 和 这些原始字符。这个技巧我几乎每周都会用到写教程、写 README、写 changelog 都有需求。另一个常见陷阱是在代码块里展示 HTML 标签。前面提到过字符串内不需要转义尖括号但在某些对安全要求极高的渲染环境里代码块内的script标签可能会被过滤掉或触发警告。这种情况不多见但如果你在写面向 CMS 或论坛的文档建议明明可以避免就不用代码块展示 HTML改用实体字符 script 来绕开过滤。代价是读者看到的不是完整标签而是实体字符不够直观算是少数派场景的取舍。4.1 代码块里还能不能再嵌套代码块严格意义上Markdown 不支持代码块嵌套代码块。你可以在外层代码块里展示内层代码块的源码但渲染结果只会有外层一个代码块内层内容按原样输出。想实现代码块中有两个子块的可视化效果官方 Markdown 没有这个语法你得借助表格、引用块或其他扩展。我的建议是不要试图在标准 Markdown 里嵌套代码块把复杂结构拆成多个代码块之间用说明文字衔接。4.2 数学公式和代码块的爱恨情仇搜索热词里有markdown 数学符号markdown数学公式插件说明很多人会在笔记里写公式。数学公式和代码块有个容易混淆的边界有的渲染器用 $$...$$ 表示块级公式有的用 \[..\]跟代码块的围栏语法完全是两回事。如果你在代码块里写一段 LaTeX 公式比如一段需要展示给读者的推导过程它是不会被当成公式渲染的——代码块内的所有内容被冻结包括 $$ 标记。反过来如果你想在普通文字里写一个公式却用反引号把它包起来比如 Emc^2那它会被当成行内代码而不是行内公式字体变成等宽体不会按公式排版。这是一个非常常见的误用很多人想让公式显得独立就顺手用了代码块结果 LaTeX 语法全都没有生效。正确做法是区分场景要展示带高亮的代码用代码块要展示数学推导和公式用数学公式语法不要用代码块包公式。部分编辑器如 Typora 支持数学公式内嵌在段落中用 $...$ 行内写法这个和行内代码互斥同一内容只能二选一。4.3 代码块里有没有注释要不要写注释讨论到这里其实涉及一个文档写作习惯的问题代码块内部要不要写注释、写多少注释。我的看法是Markdown 代码块里的代码注释应该遵循代码本身的规范而不是 Markdown 的规范。代码块内部保留原样输出所以 Python 的 # 注释、JS 的 // 注释、HTML 的 注释都按源码处理不会被 Markdown 误解析。很多新手以为在代码块里写 # 注释会被当成 Markdown 标题这是错觉——前面说过代码块是保护区井号在里面就是井号。所以放心写注释这是代码块可以放心的一个地方。真正建议少做的是在代码块内部用大量中文长句做注释因为代码块是等宽字体中文在其中的排版往往歪歪扭扭阅读体验不佳有耐心的建议把核心注释挪到代码块外部的正文里用 Markdown 的段落结构来解释。5. 编辑器渲染差异Typora、Obsidian 与 .md 文件打不开的问题聊完语法本身得说说现实世界的编辑器差异。这也是为什么很多人照着网上教程写代码语法换到另一个软件里效果全变了。Markdown 是标准但标准下的渲染器各有各的脾气了解这些差异能让你少掉很多头发。先说 Typora。它走的是所见即所得路线输入 Markdown 符号后立刻预览效果写代码块、改语言标注都是即时反馈。Typora 的背后有一个比较严格的解析器对空行的处理、对行尾空格的处理都偏向 CommonMark 的一致性所以 Typora 里排出来的效果拿到 GitHub 上多数不变形。它对数学公式、Mermaid 图表的支持也很完善这是很多技术博主选它的原因。但Typora 中文破解版这个热词让我有点警惕——Typora 在 1.0 之后转为付费软件网上流传的各种破解版绿色版鱼龙混杂有的版本里预置了可执行的广告脚本有的下载站把它捆绑了其他安装包。我的建议一直很简单写文档的工具最好用正规渠道的正版Typora 一次性买断价格并不高或者直接用免费的替代品完全没必要为此承担安全风险。再说 Obsidian。它是基于本地 Markdown 文件的笔记软件默认渲染偏向 CommonMark 一堆扩展插件代码高亮依赖 Prism 或 highlight.js换语言标识后高亮效果和 Typora 未必一致特别是 C、Rust 这类语言在不同高亮引擎里的效果差异很明显。Obsidian 的强项是双链和插件生态如果你主要在 Obsidian 里写笔记和知识管理那它就是你的主力环境语法测试以 Obsidian 的渲染为准。VS Code 是另一类。它的 Markdown 预览默认是 GitHub 风格的渲染规则接近 GFM但代码高亮依赖内置的 TextMate 语法库和 Typora 的高亮机制完全不同。VS Code 里写代码块遇到 edge case 时首先要意识到编辑器的语法高亮和预览渲染是两个不同的解析引擎编辑区里的颜色标识和预览区的颜色可能不一致。我见过不少人误会我明明写了语言标识为什么编辑区还是没高亮其实是编辑区把 Markdown 文件当成普通 Markdown 解析代码块的围栏语法识别到了但语言高亮要等预览才生效需要你装了对应的主题或插件才能同步。5.1 .md 文件怎么打开别再双击后面对记事本了.md 文件怎么打开能上热搜说明大量新手接触 Markdown 的第一个瓶颈不是语法而是工具链下载了一个 .md 文件双击弹出来的是记事本满屏都是井号和星号一下就没兴趣了。其实打开 .md 文件的方式非常多我列一下最实用的几条路径浏览器打开在 GitHub 仓库里直接点文件即可GitHub 会自动渲染 Markdown 为格式化文档。Typora / Obsidian 打开如果你已经装了编辑器右键 .md 文件选择打开方式或者直接拖到编辑器窗口里。VS Code 打开文件拖进 VS Code按 CtrlShiftV 打开预览面板立刻看渲染效果几乎零成本。命令行工具如果你在 WSL 或 Linux 终端里可以装一个 mdless、glow 之类的工具在终端里渲染查看适合快速浏览和脚本处理。这里有个建议如果你是重度 Markdown 用户给 .md 文件设置正确的默认打开方式通常我们会设置成 Typora 或 VS Code。这样下载文件、双击打开直接就进入渲染好的文档界面不会再有记事本看排版的糟糕体验。Windows 系统里文件右键属性可以修改默认程序macOS 里用显示简介修改打开方式这两步值得先做。5.2 图片路径问题为什么 md 文件换台电脑图片全挂图片路径是另一个高频热词——markdown图片路径、onenotemdexporter导出markdown图片路径不对。代码语法本身不涉及图片但 Markdown 文档里经常同时包含代码块和图片而图片路径的处理逻辑直接影响读者体验。Markdown 里插入图片的语法是 path 可以是相对路径也可以是绝对路径。相对路径比如 ./images/1.png它相对于当前 .md 文件所在的目录绝对路径比如 /assets/1.png它相对于网站的根目录或磁盘根目录。问题出在很多笔记软件会把你粘贴的图片自动存到一个隐藏的附件目录然后写进文档的却是相对路径或特殊协议路径。当你把 .md 文件单独发出去、或者移动到另一个目录时图片路径的基准变了图片自然就裂了。我的建议是如果写的是跨平台、可移植的 Markdown 文档图片统一用相对路径且图片要和 .md 文件放在同一个目录树的固定位置常见的做法是建立一个 images 目录文档里写 ./images/文件名.png。如果是在博客平台上发布直接上传图片得到 URL用绝对 URL 最可靠。用 Obsidian 的话可以设置附件默认存放路径到当前文档相同文件夹减少跨文件夹路径的困惑。另外一个隐藏技巧GitHub 的 README 图片尽量用 raw URL 或在仓库内相对路径尽量避免使用第三方图床链接防止图床失效后文档变盲文。5.3 复制与粘贴的隐秘差异markdown表格复制markdown表格转换excel这两个热词背后其实也隐藏着一个代码相关的问题当你把 Markdown 文档里的表格或代码块从一个平台复制到另一个平台时复制行为本身往往不等于你看到的渲染效果。以 Typora 为例复制一个代码块粘贴到聊天工具或 Word 里时大概率变成普通文本围栏符号和换行全都保留格式完全丢光。复制表格到 Excel 也一样Markdown 表格的管道分隔符不会被 Excel 自动识别为列分隔符你需要先转换成 CSV 或制表符分隔格式才能正确粘贴进表格。所以当你在多个平台之间搬运 Markdown 内容时要么用源码文本搬运粘贴到目标平台然后用目标平台的渲染器重新格式化要么用沉浸式导出比如 Typora 导出为 HTML 或 PDF 后再复制。不要期望跨工具复制能保留一切这是 Markdown 生态的固有摩擦不是语法问题。6. 代码语法在转换链路里的失真问题现实中Markdown 很少只停留在 Markdown 编辑器里它经常要转成 Word、转成 PDF、转成 HTML、甚至转成 Excel。每一次转换都是一次渲染器换人代码语法在这种转换链里是最容易失真的一环。热搜词里dify markdown转word中序号自动编号java word 转markdownpdf转markdownmarkdown表格转换excel集中反映了这个痛点。先说 Markdown 转 Word。最常用的工具是 Pandoc一行命令就能把 .md 转成 .docx。但 Pandoc 对代码块的处理有一个很多人不知道的细节默认情况下Pandoc 转换出的代码块在 Word 里不带高亮只保留等宽字体和底纹。要让 Word 里也带高亮你需要给 Pandoc 加 --syntax-highlighting 相关参数在 Pandoc 的选项里指定高亮风格。即便如此高亮效果和 Typora 里的效果仍然可能有色差因为 Word 对换页、行距、字体的处理方式和网页完全不同。转 Word 中序号自动编号这个现象更具体。有些工具在把 Markdown 转 Word 时代码块里如果有有序列表的写法比如 1. xxx转换器会把代码块的纯文本属性丢掉重新识别为 Word 的自动编号样式导出的文档里代码块数字字号错乱、缩进变化。这个问题的根因在于Markdown 代码块经过转换器时有些库比如一些 Java 侧的 md 转 docx 库没有正确处理代码块内的文本属性导致像列表、标题这类语义残留被带进了 Word 样式。解决方案不是改语法而是换工具用 Pandoc 转换时检查 --wrap 和偏移设置用专门支持代码块原样转出的转换器或者转完 Word 之后人工修复一次代码段样式。再说 PDF。Typora 导出 PDF 时代码块默认有背景色和边框行号可以被控制是否显示。但切到自定义主题时代码块字体大小、行高比例很容易脱离整体排版节奏导出的 PDF 里代码块与正文之间出现大块留白或者代码被截断。我遇到最多的是某行代码过长横向溢出PDF 直接把这行切断没有横向滚动条可以救。解决思路有两个一是把长代码在原文档里手工换行用反斜杠续行符二是导出前调整 PDF 的页面宽度和字体大小。从语法层面讲你无法强制 PDF 渲染器出现横向滚动所以长行在 PDF 场景下必须代码作者的换行意识来保证阅读体验。html 转 Markdown和PDF 转 Markdown则是另一个方向。从 HTML 或 PDF 转出来的 Markdown代码块经常被转成缩进代码块或带着大量内联样式语言标识丢失高亮全无。这类自动转换工具的产物我一般只作为初稿使用会手工重新整理代码块的围栏和语言标注。毕竟转换器可以识别这里有代码这个事实但它很难理解这段代码是什么语言、为什么它应该高亮。公众号文章markdown格式化又是一个热门方向。公众号后台自带的编辑器对 Markdown 支持为零你必须把 Markdown 排版成富文本。常见的做法是用 mdnice、doocs/md 这类在线工具把 Markdown 渲染成带样式的 HTML再粘贴到公众号编辑器。代码块是这里的重灾区很多在线工具渲染出的代码块是带内联样式的 div粘贴到公众号后代码块背景、边框、字体常常错乱。我自己的经验是公众号里的代码块尽量用短小片段长代码块粘贴后几乎都会出现样式失常而且公众号后台对行高、字间距的压缩会让长代码可读性很差。从这些转换场景里可以提炼出一个核心原则Markdown 的代码语法在标准渲染器里表现最稳定一旦进入像 Word、Excel、公众号后台这类非 Markdown 原生环境就必须接受样式折损。与其在转换后被重重问题纠缠不如在设计阶段就思考谁最终消费这份文档如果最终读者是在 Word 里过长的代码段应该提前拆行如果最终读者是在公众号代码块应该尽量短小精悍。这些经验都是代码语法之外的功夫但恰恰是最值钱的。6.1 代码块在转换中的元数据损失关于代码块转换还有一点值得专门提你的语言标识在转换中可能被丢弃也可能被错误映射成另一种语言。我试过用某些在线工具把包含 csharp 的 Markdown 转成 HTML结果代码块被渲染成 plaintext没有任何高亮。语言标识只是提示不是数据。这不是 Bug而是很多转换器对未知语言采取的保守策略认不出来的标识就按无高亮处理避免瞎高亮反而干扰阅读。所以代码块转没了颜色这类问题多数不是语法错误而是转换工具不支持该语言标识。解法很简单转成的结果里如果语言标识丢了那么转换前后都要检查一下高亮关键段是否完好。对技术写作者来说我的底线是重要文档转格式之前永远留一个 .md 源文件版本所有转换产物都是中间产物只有源文件是可长期维护的资产。6.2 用 Markdown 代码语法写非代码内容的技巧代码块不是只能放代码。我经常用代码块放配置文件、命令日志、目录树、甚至带格式的 ASCII 艺术图。代码块的最强特性就是保留原样把那种我想让读者原原本本看到的内容都往代码块里放可以让它在任何渲染器下都不变形。比如目录树写普通文本时树状结构的空格和对齐很容易被 Markdown 的段落折叠逻辑破坏。放进代码块后空格全部保留结构一目了然。再比如一段逻辑流程也可以做成代码块风格的无序列表用等宽字体展示层层嵌套。这其实是用代码块的语法来规避 Markdown 文本换行折叠的取巧方式很实用。要注意的就是代码块不是一个无样式容器它有自己的底色和边框用得多了文档会像大块矩阵所以每次用代码块装非代码内容时都问自己一次这段内容是否真的需要绝对保留原样如果只是想让排版好看应该用列表或引用块而不是代码块。7. 把 Markdown 当结构化语言用AI 提问场景下的代码输入最后一个热搜词很有意思——对deepseek提问是使用自然语言还是markdown更容易让ai明白指令。这问题从技术写作的角度看其实答案很清晰给 AI 的输入本身就是一份指令文档而 Markdown 的代码块正是为指令文档中的精确信息设计的。当你的提示词里包含一段 JSON、一段日志、一段配置文件、一段代码样例时如果直接以自然语言的形式塞进长对话里模型要自己从一整段散文式的描述里去猜哪部分是可执行代码、哪部分是你要修改的目标、哪部分是解释性文字。这不可避免会产生解析噪声——模型可能把注释当成指令、把代码当成描述、把描述当成代码。用代码块把这种精确数据包起来实际上等于告诉模型这里面是一个整体单元你按代码来理解不要混淆。我常用的做法是三层结构开头用自然语言描述任务背景和目标中间用代码块给出输入数据和期望输出格式末尾用简短的自然语言强调限制条件。这个结构与背景—输入—约束的指令设计模式高度一致而代码块恰好负责输入这一层让大段结构化数据不再与语言混在一起。特别是 JSON 类型的输入包进代码块后模型更容易感知到 JSON 结构的层级关系给出的应答也更贴合结构本身。还有一点关于 Mermaid。搜索词里markdown preview mermaid support反映出很多人在 Markdown 编辑器里写 Mermaid 图表代码结果预览区空白一片。Mermaid 不是 Markdown 的标准语法而是一个流行的图表扩展。Typora 原生支持 mermaid 代码块VS Code 需要装 Markdown Preview Mermaid Support 插件Obsidian 需要装社区插件。所以如果你写了 mermaid 代码块却没有预览先确认当前编辑器是不是安装了对应的 Mermaid 扩展这不是语法写错了是渲染环境没配对。AI 场景下的 Mermaid 也一样你可以让 AI 帮你生成 Mermaid 代码然后粘贴到支持 Mermaid 的编辑器里预览再迭代修改。这个流程本质上也是代码语法 渲染环境的配合底层逻辑和写 Markdown 代码块完全一致。7.1 提示词里代码块的边界控制用代码块给 AI 输入信息时边界控制比日常写作还要严格。因为模型会解析你的代码块如果代码块内外信息交叉嵌套模型反而会被绕晕。我总结出几条实践原则一个代码块只放一种类型的数据不要把 JSON 和 shell 命令混在一个块里。代码块内不要写大段解释性文字解释放代码块外代码块里只放数据本身。如果数据里本身包含三个反引号外层围栏记得用四个否则模型也会被误导以为围栏提前闭合。在代码块开头第一行写上数据格式提示比如 json 本身就是给模型看的格式提示引导它用 JSON 的逻辑处理内部内容。这些原则和写给人看的文档其实是相通的只是在 AI 场景里错误容忍度更低——给人类读者造成轻微困惑的歧义给模型可能直接导致输出结果完全跑偏。7.2 Markdown 代码语法与其他结构化语法的边界最后想理清一个容易混淆的概念Markdown 代码语法和代码片段管理工具或代码高亮库是两回事。Markdown 负责的是文本级的围栏标注它本身不执行代码、不编译不运行只是标记哪里是代码区域。实际的高亮动作由渲染器里的语法高亮引擎完成比如 highlight.js、Prism、Shiki这些库各有各的语言标识库覆盖范围。所以你在某个编辑器里写的 python 换到另一个编辑器可能高亮效果完全不同这不代表你写错了而是底层高亮引擎换了。同理某个代码块在网页上显示包含行号和复制按钮那是前端框架基于代码块语义做的增强不是 Markdown 语法本身的功能。理解这一层你就能更理性地看待为什么同样一份 Markdown 在不同的地方长不一样这个问题。诚实地讲Markdown 的代码语法在语法层面上真的非常简单算上所有细节也就几千字能讲完。真正复杂的是它所在的整个生态编辑器的差异、渲染器的差异、转换链路的差异、使用者习惯的差异。这也是为什么我说代码语法只是起点渲染生态才是真正的战场。你越早建立这种生态观越少在具体某个软件的渲染怪癖上浪费时间。我自己现在写任何技术文档对代码块的使用已经形成一套近乎固定的习惯短命令和文件名用行内代码完整可运行的片段用带语言标注的围栏代码块长代码块提前手工拆行避免转换截断不依赖行尾空格做软换行图片全部放进 images 目录用相对路径引用。这套习惯本身不复杂但它为我节省的调试时间非常多。如果你还在被明明写对了却渲染不对这类问题反复困扰不妨也给自己定一套类似的固定规矩越简单越好能自动化就自动化然后把多余精力留给内容本身。
