Markdown 常见语法整理

Tue, 18 Apr 2023 15:00:00 +0800

为什么写一篇 Markdown 语法 Demo

Markdown 这东西看着简单，写多了你会发现：

不同博客平台、不同文档系统、甚至同一个工具的不同版本，支持的语法和扩展不一致
表格的对齐符号有人记不住
链接、图片、脚注的语法长得像但顺序不一样
代码块的语言标识不写就没高亮
Mermaid、KaTeX、警告框这些"扩展语法"很多人不知道

这篇是给我自己——也给所有用 Markdown 写技术博客的人——一份能直接收藏的速查 + Demo。每一节都给出实际渲染效果，复制即用。

本博客基于 Hugo + hugo-theme-stack，使用 Goldmark 作为 Markdown 渲染器。后文出现的"Hugo/Stack 主题特有"指的就是这套环境。

一、标题

1
2
3
4
5
6


# H1 标题
## H2 标题
### H3 标题
#### H4 标题
##### H5 标题
###### H6 标题

实战建议：

博客文章不要写 #——文章标题在 front matter 里已经有 title，正文从 ## 开始
层级不要超过 4 级——太深的层级阅读和导航都变差
标题前后留空行，避免渲染粘连

二、行内格式

1
2
3


**粗体** *斜体* ~~删除线~~ `行内代码`
[链接](https://example.com)
**_组合效果_**

渲染：粗体、斜体、~~删除线~~、行内代码、链接。

实战建议：

粗体优于斜体——中文里斜体可读性差
行内代码用反引号——API、UserService、createTime 这些标识符都该用
不要滥用粗体——一段里超过 3 处加粗等于没加粗

三、段落与换行

Markdown 用空行分段，单个换行不是分段：

1
2
3
4


这是第一段。
这一行虽然换行了，但还在第一段。

这是第二段。

如果真要在一段内强制换行（不分段），用两个空格 + 换行：

1
2


第一行末尾两个空格 
第二行

或者用 <br> 也行，但能不用就不用。

四、列表

无序列表

1
2
3
4
5


- 项目一
- 项目二
 - 嵌套项目
 - 又一个嵌套
- 项目三

有序列表

1
2
3


1. 第一步
2. 第二步
3. 第三步

任务列表（GFM）

1
2
3
4


- [x] 完成需求评审
- [x] 写代码
- [ ] 写单元测试
- [ ] 写文档

渲染：

完成需求评审
写代码
写单元测试
写文档

五、链接与图片

1
2
3
4
5
6


[GitHub](https://github.com)
[带 title](https://github.com "悬浮提示")
[相对链接](../another-post/)

![图片描述](path/to/image.png)
![图片带 title](path/to/image.png "图片悬浮文字")

实战建议：

图片描述（alt）一定要写——SEO + 无障碍 + 加载失败时显示
优先用相对路径——博客域名换了不会失效
大图用 Hugo 的 image processing： shortcode

六、引用块

1
2
3
4
5
6


> 这是引用的第一行。
> 这是引用的第二行。
>
> > 嵌套引用。

> **加粗的引用**——可以包含其他格式。

渲染：

这是引用的第一行。这是引用的第二行。

嵌套引用。

引用最常用的场景是：

标记别人的话（“鲁迅说……"）
强调结论
给小贴士/重要提示加个视觉标签

七、代码块

1
2
3
4
5
6
7


\`\`\`java
public class Hello {
 public static void main(String[] args) {
 System.out.println("Hello, world!");
 }
}
\`\`\`

渲染：

1
2
3
4
5


public class Hello {
 public static void main(String[] args) {
 System.out.println("Hello, world!");
 }
}

实战建议：

永远写语言标识——java、python、bash、yaml、json、sql，否则没语法高亮
不要在代码块里写废话注释——读者要的是能跑的代码
复制按钮：本博客主题渲染时自带，无需额外标记

八、表格

1
2
3
4


| 列 1 | 列 2 | 列 3 |
| :----- | :----: | -----: |
| 左对齐 | 居中 | 右对齐 |
| 内容 A | 内容 B | 内容 C |

渲染：

列 1	列 2	列 3
左对齐	居中	右对齐
内容 A	内容 B	内容 C

对齐规则：

:---：左对齐
:---:：居中
---:：右对齐
---：默认（左）

九、分隔线

1

---

或者：

1
2


***
___

效果都一样：

十、转义字符

要在文中显示 Markdown 的特殊字符，用 \ 转义：

1
2
3
4


\* 这不是斜体
\` 这不是代码
\[ 这不是链接
\# 这不是标题

十一、Mermaid 图（Hugo Stack 主题支持）

1
2
3
4
5
6
7
8


```mermaid
flowchart LR
 A[开始] --> B{判断}
 B -->|是| C[执行]
 B -->|否| D[跳过]
 C --> E[结束]
 D --> E
```

渲染：

flowchart LR
 A[开始] --> B{判断}
 B -->|是| C[执行]
 B -->|否| D[跳过]
 C --> E[结束]
 D --> E

Mermaid 支持的图类型很多——流程图、时序图、类图、ER 图、甘特图、状态机。日常写技术博客最常用的是 flowchart、sequenceDiagram、 classDiagram 三种。

时序图示例

sequenceDiagram
 Client->>Server: HTTP 请求
 Server->>DB: 查询
 DB-->>Server: 结果
 Server-->>Client: HTTP 响应

类图示例

classDiagram
 class Animal {
 +String name
 +eat()
 }
 class Dog {
 +bark()
 }
 Animal <|-- Dog

甘特图示例

项目排期、迭代计划用甘特图表达最直观：

gantt
 dateFormat YYYY-MM-DD
 title 项目排期

 section 需求阶段
 需求评审 :done, a1, 2023-04-01, 5d
 原型设计 :done, a2, after a1, 4d

 section 开发阶段
 后端 API :active, b1, 2023-04-12, 10d
 前端页面 : b2, after a2, 8d

 section 测试 & 发布
 联调测试 : c1, after b1, 5d
 上线 :crit, c2, after c1, 1d

十二、KaTeX 数学公式（需 `math: true`）

文章 front matter 里设置 math: true，就能写 LaTeX 公式：

1
2
3
4
5
6
7


行内：$E = mc^2$

块级：

$$
\int_{a}^{b} f(x)\,dx = F(b) - F(a)
$$

渲染需要主题加载 KaTeX——本主题原生支持。不需要数学的文章不要打开 math，加载 KaTeX 会拖慢页面。

十三、HTML 嵌入（默认禁用）

很多 Markdown 工具默认允许在 Markdown 里写 HTML：

1
2
3
4


<details>
<summary>点击展开</summary>
这里是隐藏内容。
</details>

但 Hugo 的 Goldmark 默认 unsafe = false——HTML 会被静默丢弃。如果业务需要嵌入 HTML：

改 markup.toml 把 unsafe = true（小心 XSS）
用 Hugo Shortcode（推荐）

十四、Shortcodes（Hugo 特有）

Hugo 提供了 shortcode 机制——比 HTML 安全，比 Markdown 强大。Hugo 内置了若干常用 shortcode：

1
2
3
4
5


{{< figure src="cover.png" caption="封面图" >}}

{{< youtube id="VIDEO_ID" >}}

{{< gist USERNAME GIST_ID >}}

上面代码块里的 {{< ... >}} 是 Hugo 在文档中展示 shortcode 不被解析的转义写法——实际使用时去掉里面的 /* */。

各主题也常自带专属 shortcode，比如折叠块、提示框、画廊等——具体可见自家主题文档。

十五、其他扩展语法

下面这几个不属于 CommonMark 核心，但 Hugo Goldmark + 主流博客引擎多数支持。

上标 / 下标

1
2
3


面积 = 长 × 宽，公式记作 S = a^2^

化学式：H~2~O，CO~2~

需要在 markup.toml 的 [markup.goldmark.extensions] 下打开 superscript / subscript 扩展。

脚注

1
2
3
4


正文里挂一个脚注[^1]，再补一个[^note]。

[^1]: 这是脚注内容，会出现在文章最末。
[^note]: 命名脚注也可以。

渲染时上标会变成可点击的链接，跳到文末的脚注列表——适合放参考文献、补充说明。

任务列表（再提一次）

很多 Markdown 教程把任务列表算扩展——但 GFM 已经标准化，所有现代渲染器都支持，前文已展示。

表格对齐与多行

复杂表格需要对齐符号 + 每个单元格不要换行——| 必须在同一行。需要单元格内换行用 <br>（要求 unsafe = true 或主题支持）。

十六、写作时的几条小建议

1. 段首不要直接进代码块

1
2
3
4


## 标题

```java
// 反面教材：紧贴标题就是代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10



正确写法是：

```markdown
## 标题

下面是核心代码：

```java
// 代码

1
2
3
4
5
6
7
8
9



读者需要"前置上下文"才知道这段代码要看什么。

### 2. 列表里包含代码块要缩进

```markdown
1. 第一步：
 ```bash
 git clone xxx

第二步：
1

cd xxx

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36



否则代码块会"破"出列表。

### 3. 中英文之间留空格

虽然 Markdown 不强制，但中英文之间留空格能显著提高可读性：

| 写法 | 效果 |
| :---------------------- | :--------- |
| 用Spring Boot开发 | 别扭 |
| 用 Spring Boot 开发 | 顺眼 |

也可以用 [autocorrect](https://github.com/huacnlee/autocorrect) 这种工具自动加空格。

### 4. 引用图床要慎重

直接 `![](https://外部图床/xxx.png)` 看着方便，但：

- 图床可能挂掉，文章变残
- 防盗链
- 加载速度

**博客图片最好用相对路径放在 page bundle 里**，由 Hugo 处理。

---

## 十七、调试技巧

### 看一篇博客的渲染源码

浏览器右键"查看页面源代码"——看一下 HTML 是怎么生成的。Hugo 的 Goldmark 有很多细节（自动加 ID、表格滚动包装、代码块复制按钮）都体现在 HTML 上。

### 本地预览

```bash
hugo server -D

实时看渲染效果，比每次 push 上线快得多。

Lint 工具

markdownlint 可以检查格式——空行、标题层级、列表缩进——保持风格一致。

小结

把全文压一句：

Markdown 看似自由，但写技术博客时风格、扩展、可移植性都要管。能用通用语法就别上扩展，必须用扩展时优先选有 fallback 的（Mermaid、KaTeX 都行）。

留几条作为"硬性规范”：

代码块永远标语言
图片永远写 alt 描述
中英文之间留空格
标题层级不超过 4 级
任务列表 / 表格对齐符 / 链接相对路径——这些常用语法记牢

最后——Markdown 不是设计文档语言，是写作语言。它的所有特性都为"专注内容"服务。当你开始想"这个怎么用 Markdown 表达" ，先问一下"这个真的需要表达吗"。

写作 on 牛哥聊技术

Markdown 常见语法整理

为什么写一篇 Markdown 语法 Demo

一、标题

二、行内格式

三、段落与换行

四、列表

无序列表

有序列表

任务列表（GFM）

五、链接与图片

六、引用块

七、代码块

八、表格

九、分隔线

十、转义字符

十一、Mermaid 图（Hugo Stack 主题支持）

时序图示例

类图示例

甘特图示例

十二、KaTeX 数学公式（需 math: true）

十三、HTML 嵌入（默认禁用）

十四、Shortcodes（Hugo 特有）

十五、其他扩展语法

上标 / 下标

脚注

任务列表（再提一次）

表格对齐与多行

十六、写作时的几条小建议

1. 段首不要直接进代码块

Lint 工具

小结

十二、KaTeX 数学公式（需 `math: true`）