文章介绍了Markdown中嵌套代码围栏的使用方法，重点遵循CommonMark规范，并适用于GitHub Flavored Markdown。内容涵盖基础与高级代码围栏及代码跨度的使用规则，通过幽默的叙述方式解释技术细节。

Markdown中的嵌套代码块

作者：Susam Pal
发布日期：2026年1月19日

本文通过一个虚构角色Corey Dumm的故事，生动地讲解了在Markdown中处理嵌套代码块和代码段的技巧。文章主要基于CommonMark规范，同时也适用于GitHub Flavored Markdown（GFM）。

主要内容

1. 基础代码块

   • 使用三个反引号（```）创建代码块时，如果内容本身包含三个连续反引号，会导致代码块提前结束。
   • 示例中Corey的"头发"（三个反引号）在渲染时丢失，因为被误认为是代码块结束标记。

2. 高级代码块解决方案

   • 使用波浪线（~~~）作为代码块分隔符
   • 使用超过三个的反引号（如``````）作为分隔符
   • 这两种方法都能安全地包含内部的反引号内容

3. 基础代码段问题

   • 内联代码段使用单个反引号时，如果内容包含反引号会导致问题
   • 示例中Becky Trace的"头发"（两个反引号）会破坏代码段结构

4. 高级代码段解决方案

   • 使用多个反引号作为分隔符（如````）
   • 在内容前后添加空格，渲染时会自动去除一个空格
   • 这样可以安全地包含内部的反引号

5. 规范依据

   • 引用CommonMark 0.30规范说明：
     • 代码块分隔符可以是至少三个反引号或波浪线
     • 代码段分隔符可以是任意数量的反引号
     • 内容首尾的空格会被自动去除一个

实用建议

• 当需要嵌套包含反引号的内容时：
  • 对于代码块：使用波浪线或更多反引号作为分隔符
  • 对于代码段：使用多个反引号作为分隔符并在内容前后加空格

这些技巧可以帮助避免Markdown渲染时的意外问题，确保代码内容完整显示。

查看完整规范
评论 | #web | #technology

以下是评论内容的总结：

1. 关于代码围栏的灵活性

   • 支持观点：代码围栏可以使用至少三个反引号或波浪号，但不同实现存在兼容性问题
     "Any number of backticks or tildes is allowed, as long as that number is at least three"
     "bad implementations was the ultimate deal breaker"
   • 反对观点：当前设计存在歧义，应使用更明确的起始/结束标记
     "Why add such ambiguity... What if I start with 4 backticks and end with 5?"
     "All these complications would have been avoidable with... better choices of symbols"

2. 替代方案建议

   • 使用不同符号（如[[[/]]]）或Postgres风格的$tag$语法
     "For example one could have used brackets"
     "Postgres solves it by using $something$ whatever $something$"
   • 长度前缀法或Org-mode等现有方案
     "length-prefixing everything makes lot of stuff easier"
     "org-mode to the rescue ;p"

3. 实际应用场景

   • 在LLM中使用不同围栏符号避免冲突
     "If I ask for markdown in a ~~~ code fence... all would be right with the world"
   • GitHub建议注释采用多反引号方案
     "This is also how you handle adding code blocks in GitHub comment suggestions"

4. 对Markdown设计的批评

   • 规范充满例外情况
     "a specification that consists entirely of exceptions"
   • 简单但不够严谨的设计哲学
     "Markdown assumes the user won’t do anything silly"

5. 实用技巧

   • 通过HTML标签或增加围栏数量解决嵌套问题
     "used html elements like

      and "
     
     "surrounding code with more ticks than maximum number... allows arbitrary nesting"