markdown代码块终极玩法语法高亮、行号、diff 展示、折叠、mermaid 图表、PlantUML

代码块是 Markdown 的灵魂，尤其在技术文档、博客、README 中。2026 年，GFM（GitHub Flavored Markdown） + 静态站点工具（如 VitePress、Docusaurus） + Obsidian 插件生态让代码块玩法爆炸升级。
我们把六大终极技巧拆开讲：语法高亮、行号、diff 展示、折叠、Mermaid 图表、PlantUML。所有示例已实测兼容主流平台。

一、语法高亮（Syntax Highlighting）——基础但必备

语法：围栏代码块 + 语言标识

```js
console.log("Hello, Markdown!");


**渲染效果**（GitHub / VS Code / Obsidian / VitePress）：
```js
console.log("Hello, Markdown!");

支持语言（GitHub 200+ 种，常见缩写）：

js / javascript / ts / typescript
python / py
html / css / json / yaml / bash / sh
diff（后面详讲）
mermaid（下面详讲）

技巧：

语言标识写错 → 高亮失效 → 用常见缩写
无语言 → 纯文本（安全但丑）
行内代码：`code` → 无高亮

二、行号（Line Numbers）——调试/教学神器

GitHub 原生：2026 年仍不支持（无内置行号）
跨平台解决方案：

VitePress / MkDocs（推荐静态博客）：

```ts:line-numbers
const a = 1;
const b = 2;
console.log(a + b);

或全局配置 + 覆盖：
```ts:line-numbers=5  // 从第5行开始编号

渲染：带左侧灰色行号。

Obsidian：插件实现
- Code block enhancer / Advanced Codeblock / Code Styler 等插件
- 设置中全局开启，或 per-block 用 frontmatter / 属性
VS Code 预览：Markdown All in One / Markdown Preview Enhanced 插件支持 :line-numbers

小结：GitHub README 里想行号？用 VitePress 建站，或截图 + 标注。纯 GFM 里无解。

三、Diff 展示——代码变更神器

语法：语言标识用 diff

```diff
- 旧代码（红色背景）
+ 新代码（绿色背景）
! 警告行（橙色，有些渲染器支持）

渲染效果（GitHub / GitLab 支持）：

- 旧代码（红色背景）
+ 新代码（绿色背景）
! 警告行（橙色，有些渲染器支持）

实战技巧：

展示 PR 变更、API 修改、配置 diff
结合高亮：先写语言，再 diff（部分平台支持 diff js 但不推荐，纯 diff 最稳）
常见坑：+ / - 必须在行首，前面不能有空格

四、折叠（Collapsible / Folding）——长代码收纳

原生 Markdown / GFM：无内置折叠
平台特定实现：

Obsidian（阅读/编辑模式）：
- 用插件：Collapsible Code Blocks / Code Block Enhancer
- 或 hack：details + summary（HTML 嵌入）
```
<details>
<summary>点击展开长代码</summary>

```js
  // 很长的代码...
```
静态站点（VitePress / Docusaurus）：
- 用 admonition / details 插件
- 或自定义组件包裹代码块
GitHub：不支持折叠 → 用截图或拆分成多个小块

推荐 hack（几乎全平台兼容）：

<details open>
<summary>展开查看完整示例</summary>

```python
print("折叠内容在这里")

五、Mermaid 图表——文本画图王者

语法：语言标识 mermaid

```mermaid
graph TD
    A[Start] --> B{Decision?}
    B -->|Yes| C[Success]
    B -->|No| D[Fail]
    C --> E[End]
    D --> E

渲染效果（GitHub 原生支持，Obsidian / VitePress 需插件或内置）：

graph TD
    A[Start] --> B{Decision?}
    B -->|Yes| C[Success]
    B -->|No| D[Fail]
    C --> E[End]
    D --> E

支持类型（2026 年 GitHub）：

flowchart / sequenceDiagram / classDiagram / stateDiagram / erDiagram / journey / gantt / pie / requirementDiagram / gitGraph / mindmap / timeline / zenuml / packetDiagram / c4 / sankey

技巧：写复杂图用在线编辑器（mermaid.live）生成代码再贴。

六、PlantUML —— UML 图专业选手

语法：语言标识 plantuml

```plantuml
@startuml
actor User
User -> System: Login
System --> User: Success
@enduml

预期渲染效果（在支持 PlantUML 的环境）：

会生成一个简单的 UML 时序图：

左侧出现一个“User”小人（actor）
一条实线箭头从 User 指向 System，标签为“Login”
一条虚线返回箭头从 System 指向 User，标签为“Success”

各平台实际支持情况（2026 年现状）：

GitHub（README、Issue、Discussion）：
不支持 PlantUML 渲染。
代码块只会显示为普通灰色源码块（@startuml … @enduml 全部可见，无图形）。
→ 想在 GitHub 显示 PlantUML 图，必须用外部服务生成图片后嵌入。
Obsidian：
优秀支持。安装 obsidian-plantuml 插件后，实时渲染成 SVG 或 PNG（可在插件设置中选择格式、分辨率等）。
Typora / MarkText / VS Code（带 PlantUML 扩展）：
本地预览时通常能直接渲染成图（需安装对应 PlantUML 或 kroki 扩展）。
VitePress / MkDocs / Docusaurus 等静态站点生成器：
- 推荐使用 kroki 插件（或 kroki 官方集成）
- 或者手动嵌入 kroki.io 生成的图片链接（最通用方案）：

总结 Checklist（代码块终极玩法）

高亮：```js:disable-run
行号：VitePress :line-numbers / Obsidian 插件
Diff：```diff + / - 开头
折叠：HTML <details><summary>
Mermaid：```mermaid + flowchart 等
PlantUML：插件 / kroki 转图

markdown代码块终极玩法 语法高亮、行号、diff 展示、折叠、mermaid 图表、PlantUML