markdown语法代码块

判断 Markdown 代码块是否规范，主要看三点：是否使用围栏包裹、是否明确标注语言、围栏数量与缩进是否一致。日常写作优先使用围栏代码块；缩进代码块只在兼容旧解析器或处理极短纯文本时使用。

一、优先使用围栏代码块

围栏代码块用三个反引号 ```` ``` ```` 开始，三个反引号结束。开启围栏后同一行紧跟语言标识，例如： python def main(): print("hello") 围栏内内容原样保留，Markdown 语法不会解析，适合放 HTML、模板、配置、程序代码。结束围栏必须单独成行，数量不少于开始围栏。多数平台还支持波浪线 `~~~` 作为围栏符号，但反引号更通用。

二、语言标注要准确

语言标识决定渲染器如何高亮代码。常见标识包括 `python`、`javascript`、`java`、`c`、`cpp`、`csharp`、`go`、`rust`、`ruby`、`php`、`sql`、`bash`、`json`、`yaml`、`html`、`css`、`diff` 等。标注与开启围栏之间不要有空格，例如 `` ```python `` 正确，````` python `` 错误。 不确定语言时，宁可不标注或使用 `text`，避免错误高亮干扰阅读。纯文本、输出示例、ASCII 图可以不标。不同平台对语言别名的支持有差异，发布前应确认目标渲染器是否识别所选标识。

三、缩进代码块只在必要时使用

缩进代码块要求每行至少缩进四个空格或一个制表符，空行也要保持相同缩进。它通常用于极短的纯文本，或需要兼容不支持围栏的旧解析器。 在列表项或引用块中使用缩进代码块时，缩进需要叠加。例如列表项内容本身缩进两空格，代码块需要再缩进四空格，共六空格或更多。缩进代码块容易与普通段落缩进混淆，现代写作建议默认使用围栏代码块。

四、行内代码与围栏的边界

行内代码用单个反引号包裹，用于段落中的命令、文件名、变量或短代码，例如 `print("hello")`。它不保留换行，不能替代多行代码块。多行内容或需要保留格式的代码，应使用围栏代码块。 如果行内代码本身包含反引号，使用双反引号包裹，例如 `` `code` ``。两端反引号数量必须一致，且与内容之间不要有空格。

五、嵌套、转义与特殊情形

围栏代码块内出现反引号时，增加围栏数量或改用波浪线。例如某段代码需要显示三个反引号，可以用四个反引号围栏： `` 这里的 ``` 会被原样显示 `` 在列表、引用块中嵌套围栏代码块时，围栏要与列表项内容缩进对齐，否则解析器可能提前结束列表或引用。GFM 对列表内围栏代码块支持较好，但 CommonMark 在不同实现中可能有差异。代码块内部不需要转义 Markdown 符号，原有符号不会生效。

六、发布前检查清单

• 开启与结束围栏数量是否一致，结束围栏是否单独成行。
• 语言标识是否紧贴开启围栏，拼写是否被目标平台支持。
• 列表或引用中的代码块缩进是否足够，避免破坏外层结构。
• 行内代码两端反引号数量是否一致。
• 是否误用了缩进代码块替代围栏，导致格式漂移。
• 渲染预览中代码是否按预期原样显示，没有多余解析或高亮异常。

规范代码块的核心是：围栏稳定、语言明确、缩进受控。发布前用目标渲染器预览一次，通常可以避免绝大多数排版问题。