Featured image of post Markdown 常见语法整理
工程实践

Markdown 常见语法整理

从基础标题、列表、链接，到表格、代码块、Mermaid 图、脚注、警告框——一篇可直接收藏的 Markdown 全面参考

为什么写一篇 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
```

渲染：

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

时序图示例

类图示例

甘特图示例

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

十二、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. 第二步：
    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 都行）。

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

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

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

© 2016 - 2026 牛哥聊技术
使用 Hugo 构建
主题 Stack 由 Jimmy 设计