Markdown 必知必会：日常写作与文档的参考手册
原创 · 约 27 分钟阅读 · 阅读 --

Markdown 必知必会：日常写作与文档的参考手册

作者: 字与码

工程实践

这篇是 Markdown 的参考手册，不是教材。它的用法是：遇到不会写的语法，到左侧目录找到对应条目，看「写法」抄代码，看「渲染结果」确认效果，再扫一眼「要点」避坑。每个语法条目都是固定的三段式——写法、渲染结果、要点——方便随时查阅。

需要说明两点：数学公式和 Mermaid 需要平台支持，本站没有接入对应插件，这两节的”渲染结果”是模拟或按代码块显示，文中已标注。

Markdown 解决什么问题

从纯文本到结构化内容

Markdown 用纯文本加少量约定符号表达文档结构：# 表示标题、- 表示列表、反引号表示代码。源文件是人类可读的普通文本，经过解析器渲染成 HTML、PDF、公众号文章等目标格式。

Markdown 源码 → 解析器（CommonMark / GFM）→ 渲染器 → HTML / PDF / 公众号

Markdown 渲染链路：源码、解析器、渲染器与目标平台

为什么它成了事实标准

GitHub 的 README、PR、issue 都吃 Markdown；Astro、Hugo、VitePress 这类静态站点把 Markdown 当一等公民；飞书、知乎、微信公众号的编辑器都提供 Markdown 导入；AI 生成文档时默认输出 Markdown。它是开发者之间交换结构化信息的默认语言。

代价是方言多：CommonMark 是标准基线，GitHub Flavored Markdown（GFM）在其上加东西，飞书、知乎、公众号又各有各的限制。同一段文本在不同平台渲染结果可能不一样——这正是本文每个条目都同时给出写法和渲染结果的原因。

基本语法

标题：用 # 表示层级

写法：

## 二级标题
### 三级标题
#### 四级标题

渲染结果：

二级标题

三级标题

要点：

  • 一个页面只用一个 #（留给文章标题），正文从 ## 开始；
  • 层级不要跳级：## 下面直接写 ####，中间缺 ###，目录结构是断的（lint 规则 MD001 会报错）；
  • 标题自动生成锚点，## 快速开始 的锚点是 #快速开始。

段落与换行：空行是分段的唯一标准

写法：

这是第一段。

这是第二段，和上一段之间必须空一行。
这一行没有空行，会和上一行被当成同一段落。

这是第三段，行尾两个空格再回车是强制换行  
这一行就会出现在新的一行。

渲染结果：

这是第一段。

这是第二段，和上一段之间必须空一行。 这一行没有空行，会和上一行被当成同一段落。

这是第三段，行尾两个空格再回车是强制换行
这一行就会出现在新的一行。

要点：

  • 段落之间必须空一行，这是 Markdown 最常见的坑；
  • 段内单个换行的行为各平台不同：严格 CommonMark 渲染成空格，GitHub（GFM）渲染成换行；
  • 可移植的强制换行写法：行尾两个空格，或用 <br>。

粗体、斜体与删除线

写法：

**粗体**，*斜体*，***粗斜体***，~~删除线~~

渲染结果：

粗体，斜体，粗斜体，删除线

要点：

  • 中文场景建议只用粗体：中文没有斜体传统，多数字体渲染斜体又难看又难读；
  • 删除线 ~~ 是 GFM 扩展，GitHub、飞书、知乎都支持，标准 CommonMark 不包含。

无序列表

写法：

- 苹果
- 香蕉
  - 大蕉（缩进两空格成为子项）
  - 小米蕉

渲染结果：

  • 苹果
  • 香蕉
    • 大蕉（缩进两空格成为子项）
    • 小米蕉

要点：-、*、+ 都能当列表符号，一个文档里不要混用（lint 规则 MD004）；子项缩进 2~4 个空格，渲染器一般都能识别。

有序列表

写法：

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

渲染结果：

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

要点：编号全部写成 1. 大多数渲染器也会自动递增，但为了源文件可读，建议手动写对；有序列表和无序列表可以互相嵌套，缩进规则一样。

任务列表

写法：

- [ ] 待办事项
- [x] 已完成事项

渲染结果：

  • 待办事项
  • 已完成事项

要点：- [ ] / - [x] 是 GFM 扩展，GitHub 和飞书支持，微信公众号原生编辑不支持。

链接：行内式与引用式

写法：

[行内式链接](https://example.com "悬停提示")

[引用式链接][ref]

[ref]: https://example.com "引用的目标"

渲染结果：

行内式链接

引用式链接

要点：

  • 引用式链接把 URL 集中到文末定义（[ref]: URL），定义行本身不会显示，长文档重复引用同一资源时很好用；
  • 仓库内文档优先用相对路径（[说明](./docs/guide.md)），仓库移动不容易断链；
  • 引用式链接的定义在渲染结果里不占位，上面你看到的只是链接本身。

图片

写法：

![图片替代文字](/images/markdown-essentials-handbook/rendering-pipeline.png)

渲染结果：

图片替代文字

要点：

  • 替代文字（alt）必填：可访问性、SEO、图片加载失败时的兜底都靠它，不要写空；
  • 相对路径在本地和静态站点里优先；知乎、公众号要求绝对 URL；
  • 图片入库前先压缩（本站规范：正文图最长边 1400px，优先 PNG）。

引用块

写法：

> 这是一段引用。
>
> > 这是嵌套引用。

渲染结果：

这是一段引用。

这是嵌套引用。

要点：引用块内的空行也要带 >，否则引用会被打断；引用里可以放代码块，代码块比 > 再多缩进即可。

行内代码

写法：

运行 `npm run dev` 即可。

渲染结果：

运行 npm run dev 即可。

要点：行内代码用一对反引号包裹，不能跨行；内容本身含反引号时，用两个反引号包裹（`code`），或改用代码块。

代码块：围栏式

写法：

```python
print("hello")
```

渲染结果：

print("hello")

要点：

  • 围栏代码块一定标注语言（python、bash、json、yaml），渲染器才能高亮，读者和 AI 才知道怎么执行；
  • 代码要完整可执行：要么给出完整命令，要么标注环境前提；
  • 缩进式代码块（行首 4 空格）是 CommonMark 语法，但无法标注语言，长文档里优先用围栏式。

代码块里展示代码块：外层围栏用更多反引号

写法（外层四个反引号，内层三个，下面的markdown代码实际上最外层还有一层五个反引号的标签，这样才能显示四个反引号的内容）：

````markdown 
```python
print("hi")
```
````

渲染结果：

```python
print("hi")
```

要点：要展示”代码块本身”时，外层围栏的反引号数量必须比内层多，否则围栏会被提前闭合。

表格

写法：

| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |
| 文字 | 文字 | 文字 |
| `\|` 转义竖线 | 空单元格 | |

渲染结果：

左对齐居中右对齐
文字文字文字
| 转义竖线空单元格

要点：

  • 第二行分隔行必须有（---），否则整个表格不被识别；
  • : 的位置控制对齐：左 :---、居中 :---:、右 ---:；
  • 单元格里的竖线要转义 \|；
  • 表格里很难放列表、多行代码，长文档里”大表格拆小表”比硬塞更可维护。

分割线

写法：

上面是文字。

---

下面是分割线后的文字。

渲染结果：

上面是文字。

下面是分割线后的文字。

要点：--- 前后都要空行，渲染成横线；如果 --- 紧跟在文字下一行（中间没有空行），会被解析成 setext 二级标题（=== 是一级标题），这是新手最常踩的坑之一。不过不同的markdown实现的表现也不一样。

转义字符

写法：

\# 不是标题
\* 不是强调
\[ 不是链接

渲染结果：

# 不是标题 * 不是强调 [ 不是链接

要点：\ 可以转义 Markdown 特殊字符；需要展示一段代码时，优先用行内代码或代码块，而不是堆一堆转义。

自动链接

写法：

<https://example.com>

渲染结果：

https://example.com

要点：尖括号包住的 URL 自动变成链接；裸 URL（不包尖括号）在 GFM 下也会自动链接。

进阶语法

标题锚点与页内目录

写法：

## 安装

跳到 [安装](#安装)

渲染结果：

安装

跳到 安装

要点：

  • 锚点由标题文本生成：空格转连字符、去掉标点，中文标题直接就是文本本身；
  • 长文档的目录可以手写锚点链接，GitHub 原生不渲染 [TOC]；
  • 本页右侧目录自动提取 ## 和 ###，所以手册型文档必须把二级标题拆细。

脚注

写法：

正文引用脚注[^1]。

[^1]: 脚注内容，可以写多行，续行要缩进。

渲染结果：

正文引用脚注1。

要点：脚注是 GFM 扩展，定义写在文末，正文用 [^1] 引用，渲染时自动编号；微信公众号不支持。

数学公式

写法：

行内公式 $E = mc^2$

块级公式：
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

渲染结果（本站未接入 KaTeX，下面一行是模拟渲染；GitHub、知乎支持真实渲染）：

行内公式：E = mc²

块级公式：

∑ᵢ₌₁ⁿ i = n(n+1)/2

要点：公式依赖平台支持，公众号原生编辑不支持 Markdown 公式；公式多的文档先定目标平台，别指望一份稿子到处贴。

Mermaid 流程图

写法：

```mermaid
graph LR
    A[源码] --> B[解析器]
    B --> C[渲染器]
```

渲染结果（本站已集成 Mermaid，flowchart LR 等图表会直接渲染成图）：

graph LR
    A[源码] --> B[解析器]
    B --> C[渲染器]

要点：Mermaid 本质是”代码块 + 平台扩展”，不支持的平台会退化成纯文本；关键流程图要么用图片，要么接受降级显示。

内嵌 HTML

写法：

<span style="color: #c0392b">这段文字是红色的</span>

渲染结果：

这段文字是红色的

要点：

  • 可用于控制图片尺寸等 Markdown 做不到的效果：<img src="..." width="600">；
  • 代价是可移植性变差（有的平台会过滤 HTML），别放脚本；
  • 复杂排版优先考虑专用工具，而不是用 HTML 硬撑。

定义列表（方言）

写法：

术语
: 定义内容（PHP Markdown Extra / Kramdown 方言）

渲染结果（多数平台不支持，会按普通段落显示）：

术语 : 定义内容（PHP Markdown Extra / Kramdown 方言）

要点：这是方言语法，不是 CommonMark/GFM 标准；跨平台发布前先验证目标平台是否支持。

平台差异

CommonMark 与 GFM

CommonMark 是标准基线，GFM 在它之上增加了：表格、删除线、任务列表、自动链接、围栏代码块语言标注、脚注。写文档时默认以 “CommonMark + GFM” 为基线最稳。

各平台支持速查

能力GitHub飞书知乎公众号本站（Astro）
表格✅✅✅部分✅
任务列表✅✅部分❌✅
数学公式✅部分✅❌❌
Mermaid✅✅❌❌❌
脚注✅✅部分❌✅
相对路径图片✅✅❌❌✅

这张表只是方向性参考，具体以目标平台实测为准。涉及表格、公式、Mermaid、脚注的稿子，先定平台再写。

换行与锚点的差异

换行行为在「段落与换行」一节说过。锚点也一样：GitHub 的标题锚点把空格转成连字符、去掉标点；飞书、知乎的锚点规则不同。跨平台复制目录链接，经常”看着一样，点进去 404”，不是你的错，是平台的锅。

图片与附件的处理

  • 本站和 GitHub 支持相对路径图片，仓库移动后只要目录一起搬就不会断；
  • 知乎、公众号要求绝对 URL，本地图片要先传到图床或平台；
  • 图片入库前压缩，避免几 MB 的大图拖慢页面。

工程实践

文档即代码

Markdown 放在仓库里，就意味着它可以走和代码一样的流程：提交、review、diff、CI 校验。团队文档的 PR 和代码 PR 一样值得审查——很多”文档和实现不一致”的问题，就是跳过 review 攒下来的。

一个文件一个主题，标题即目录

长文档拆开：一个主题一个文件，文件名用语义化 slug（如 markdown-essentials-handbook.md），首页或索引文件负责组织。文件内部标题层级就是文档的骨架，## 是一级章节、### 是子主题，写之前先列标题大纲，比先写正文再补标题好得多。

中英文混排与标点

中文文档的通行规范：中文与英文、数字之间加空格，中文标点用全角，英文标点用半角。

错误：使用Markdown写文档。
正确：使用 Markdown 写文档。

这份规范在仓库 AGENTS.md 里也有体现——规范本身就该用 Markdown 写并放在仓库里。

代码块的可执行性

手册里的代码块要能复制即用。三个检查点：

  1. 语言标注正确（bash / python / json / yaml）；
  2. 命令完整（包括进入目录、安装依赖等前置步骤）；
  3. 危险操作标注清楚（删除、覆盖、生产环境命令）。

frontmatter：给文档加元数据

静态站点（包括本站 Astro）支持 YAML frontmatter——文件开头的 --- 块，声明标题、日期、分类、封面等元数据：

---
title: "Markdown 必知必会：日常写作与文档的参考手册"
description: "一份能放在手边的 Markdown 参考手册"
pubDate: 2026-08-05
slug: "markdown-essentials-handbook"
draft: false
handbook: true
category: "工程实践"
authors: ["字与码"]
tags: ["Markdown", "文档"]
heroImage: "/heroes/markdown-essentials-handbook-hero.png"
---

frontmatter 不是装饰：站点靠它决定文章进不进列表、进不进手册、RSS 和公众号同步怎么排。字段写错最常见的后果是”页面构建过了，但文章不出现”——例如 draft: true 会直接让文章只在本地可见。

Markdown 与 AI 协作

AI 时代 Markdown 多了一个角色：机器可读的结构化规范。AGENTS.md、SKILL.md 都是 Markdown 文件，agent 按它们执行任务。给 AI 写任务说明时，同样用 Markdown 的结构化能力：

  • 用 ## 分节拆任务，而不是一大段话；
  • 用列表写验收标准，用表格写参数映射；
  • 代码块标注语言和运行环境；
  • 明确”哪些操作不能做”（对应 Destructive Actions 类的边界说明）。

让 AI 生成 Markdown 时，要求它输出可验证的内容：相对路径、语言标注、完整的可执行命令，并且不包含令牌、内网地址等敏感信息。

验证与工具

本地验证

本站的验证流程：

cd astro-site
npm run dev      # 本地预览 http://localhost:4321/blog/<slug>/
npm run build    # 构建全部页面，报错会中断

GitHub 上验证更简单：把 .md 文件放进任意仓库，GitHub 直接渲染。发公众号前先在编辑器预览，别信”通用 Markdown”。

lint 与格式化

推荐给仓库配 markdownlint，常见规则：

规则含义
MD001标题层级必须逐级递增
MD013行长限制（中文建议放宽或关闭）
MD036不要用强调代替标题
MD041文件首行应为顶层标题（有 frontmatter 时例外）
MD045图片必须写替代文字

格式化用 Prettier 或 markdownlint --fix 统一风格，避免”格式 commit”污染历史。

常用编辑器

  • VS Code + Markdown All in One：预览、目录、快捷键最省事；
  • Typora：所见即所得，适合长文；
  • Obsidian：双链和知识库场景。

一页速查表

想表达写法渲染结果
标题## 标题更大更粗的标题字
粗体**文字**文字
斜体*文字*文字
粗斜体***文字***文字
删除线~~文字~~文字
无序列表- 项圆点列表
有序列表1. 项数字列表
任务列表- [x] 项☑ 勾选项
链接[文字](url)文字
图片![alt](path)渲染为图片
引用> 文字缩进的引用块
行内代码`code`code
代码块```python高亮代码块
表格| a | b | + 分隔行表格
分割线---横线
转义\#字面 #
脚注文字[^1] + 文末定义上标脚注

局限与边界

Markdown 不是排版系统。学术论文的参考文献、复杂的书籍版式、精细的图文混排，应该用 LaTeX 或专门的排版工具，而不是在 Markdown 里堆 HTML。它也不是数据库——结构化数据用 YAML/JSON，别用表格假装。

它真正的边界是：越依赖小众扩展语法，文档的寿命越短。十年后 CommonMark + GFM 大概率还在，某个平台的私有扩展不一定在。写文档时问自己一句：这份稿子如果换平台，内容会丢吗？

参考来源

  • CommonMark 规范（spec.commonmark.org）
  • GitHub Flavored Markdown 规范（github.github.com/gfm）
  • GitHub Docs：Markdown 使用说明
  • markdownlint 规则文档
  • 本站 Astro 内容集合配置（frontmatter 字段定义）

Footnotes

  1. 脚注内容，可以写多行，续行要缩进。 ↩

打开原图 ↗