第四章 Markdown 核心语法

这章我们边写一份 README.md 学习笔记，边熟悉 Markdown。笔记里会有 Python 学习计划、资料链接、配图和一个能运行的程序；每完成一部分，就保存下来看看效果。

不用先背完整套语法。先会用这些常见写法就够了：

标题；
段落；
粗体和斜体；
列表；
链接；
图片；
引用；
行内代码；
代码块；
分隔线。

这套语法已经能应付大多数普通文档。表格、任务列表、删除线、LaTeX 和 Mermaid 也很常见，不过我们放到下一章再学：

text

表格
任务列表
删除线
LaTeX
Mermaid

它们属于常见扩展；这一章先把最通用的基础打好。

Markdown 核心语法全景地图与能力边界

4.1 标题

先从标题开始。一篇结构清楚的文章，通常会有：

text

一级标题
二级标题
三级标题

标题层级与文档大纲树

在 Markdown 里，用 # 表示标题。一个 # 是一级标题：

# 一级标题

两个 # 就是二级标题：

## 二级标题

三个 # 表示三级标题：

### 三级标题

继续加 #，可以写到六级：

#### 四级标题

##### 五级标题

###### 六级标题

Markdown 通常最多支持六级标题。

标记格式

推荐这样写：

# Python 入门

而不是：

#Python 入门

有些工具也能认出没有空格的写法，但兼容性不一定一致。井号后留一个空格更稳妥：

text

#
+
空格
+
标题内容

比如写 ## 安装 Python。

标题层级

标题不只是把字放大，它标出的是内容在文档里的层级。看这个例子：

# Python

## 基础语法

### 变量

### 列表

## 面向对象

### 类

### 继承

对应的结构是：

text

Python
├── 基础语法
│   ├── 变量
│   └── 列表
└── 面向对象
    ├── 类
    └── 继承

所以不要为了调字号随意跳级。比如这段就不太合适：

# Python

#### 变量

因为这里直接从一级标题跳到了四级标题。

可以改成：

# Python

## 基础语法

### 变量

一级标题

文章通常用一级标题作为总标题：

# Python 入门

下面各部分用二级标题：

## 安装

## 基础语法

## 函数

再往下细分时用三级标题：

### 参数

### 返回值

这样读者容易顺着层级阅读，博客、教程和课程也更容易自动生成：

目录；
页面导航；
锚点；
文档结构。

4.2 段落与换行

普通正文直接写就行，不用加特殊符号：

Python 是一种非常流行的编程语言。

要分成多个段落，就在它们之间留一个空行：

Python 是一种非常流行的编程语言。

Python 可以用于 Web 开发、数据分析、自动化等领域。

段落与换行机制对比

空行分段

Markdown 会用空行判断段落边界。比较下面两种写法：

这是第一段。

这是第二段。

如果不留空行：

这是第一段。
这是第二段。

有些渲染器仍会把它们合在一个段落里。为了让源码好读、不同工具显示一致，段落之间留一个空行就行。

段内换行

注意，源码里按了回车，不一定代表预览页面也会换行：

第一行
第二行

不少渲染器会把这两行连在同一个段落里。要开始新段落，还是留空行：

第一段。

第二段。

如果想在同一个段落里换行，可以在行尾加反斜杠：

姓名：小明\
年龄：18

预览中会分成两行，但它们仍属于同一个段落。普通正文优先用空行分段；需要明确换行时，再使用这种写法。

空格排版

在 Word 里，有时会用多个空格对齐文字：

text

姓名：张三        年龄：18

Markdown 不适合用空格排版，网页通常会把连续空格合并。它更适合描述内容结构；如果要把数据排成行列，下一章会介绍表格。

笔记预览

先新建 README.md，写下标题和两个段落：

# Python 学习笔记

今天开始学习 Python。

我会记录每周计划和遇到的问题。

保存后打开 Markdown 预览。# 应显示为一级标题，两段正文也应分开。预览就是 Markdown 渲染后的页面，源码和预览的关系稍后还会再看。

4.3 强调

文本强调语法全景与工程避坑指南

在文字两边各加两个星号，就会显示为粗体：

**这是重要内容**

通常会显示为：

这是重要内容

常用来标出重要概念或注意事项，比如：

安装之前，**必须先确认 Python 版本**。

斜体

两边各加一个星号则是斜体：

*这是斜体*

通常会显示为：

这是斜体

斜体可以轻轻强调一个词，也常用来标出外文术语：

Python 中的 *iterator* 可以翻译为“迭代器”。

粗斜体

想同时加粗和倾斜，就用三个星号：

***非常重要***

别在一篇文章里到处加粗、倾斜，真正重要的信息才值得突出。

下划线标记

也可以用下划线表示斜体或粗体：

_斜体_

__粗体__

不少人更习惯星号写法：

*斜体*

**粗体**

选哪种都可以，在同一篇文档里保持统一就好。

4.4 列表

列表类型与缩进层次解剖

行首加一个短横线，就能创建无序列表：

- Python
- Java
- JavaScript

预览中会显示为：

Python
Java
JavaScript

无序列表适合列出没有固定先后顺序的内容。例如：

FastAPI 的特点包括：

- 性能较高；
- 支持类型提示；
- 自动生成 API 文档；
- 支持异步。

无序列表标记

有些 Markdown 工具也接受 * 或 +，但项目里最好统一写成短横线：

text

例如：

- Python
- Flask
- FastAPI

统一标记后，后续修改也更省心。

有序列表

有序列表用数字加英文句点：

1. 安装 Python
2. 创建项目
3. 安装依赖
4. 启动程序

它适合写操作步骤、执行顺序或排名。例如创建 FastAPI 项目：

创建 FastAPI 项目可以按照下面的步骤进行：

1. 创建虚拟环境；
2. 安装 FastAPI；
3. 创建 `main.py`；
4. 启动开发服务器。

编号与显示

很多渲染器也允许每一项都写 1.：

1. 安装 Python
1. 创建项目
1. 安装依赖
1. 启动程序

预览时会自动排成：

text

1.
2.
3.
4.

中途要插入步骤时，这种写法省得重排编号。比如原来：

1. 安装 Python
2. 安装 FastAPI

改成每项都写 1. 后，就不用动后面的编号。刚开始学时，还是建议按顺序写清楚：

1.
2.
3.

这样更容易看懂编号和步骤的对应关系。

嵌套列表

列表项下面还可以再放一层列表：

- Python
  - Flask
  - FastAPI
- JavaScript
  - Vue
  - React

它表达的是：

text

Python
├── Flask
└── FastAPI

JavaScript
├── Vue
└── React

嵌套项要缩进。两个或四个空格都可以，选一种统一使用。

嵌套深度

Markdown 允许多层嵌套：

text

第一层
  第二层
    第三层
      第四层

层数太多就不好读。这时可以改用标题、拆分章节，或者重新整理内容。

列表适合表示局部关系；整篇结构更适合用标题或拆分章节来组织。

学习计划

继续修改前面创建的 README.md，把内容更新为：

# Python 学习笔记

今天开始学习 **Python**。

我会记录每周计划和遇到的问题。

## 本周计划

- 安装 Python
- 写第一个程序
- 记录遇到的问题

保存文件，打开编辑器的 Markdown 预览。检查“Python 学习笔记”是一级标题，“本周计划”是二级标题，下面三项显示为列表，Python 显示为粗体。
把其中一项计划改成自己的真实计划，再次查看预览。后面学到链接、图片和代码块时，可以继续补到这份文件中。

4.5 链接

链接语法解剖与双路由寻址模型

链接写成 [显示文字](链接地址)：

[显示文字](链接地址)

例如：

[Python 官网](https://www.python.org/)

方括号里是读者看到的文字：

text

Python 官网

text

https://www.python.org/

圆括号里则是实际跳转地址。

链接文字与长网址

网址直接放在正文里，有时会显得很长：

text

Python 官网：https://www.python.org/downloads/release/python-3120/

换成带说明的链接：

可以前往 [Python 官网](https://www.python.org/) 查看更多信息。

正文会更好读。

本地链接

链接也可以指向本地文件。假设目录是：

text

docs/
├── index.md
├── python.md
└── fastapi.md

在 index.md 里这样写：

[学习 Python](./python.md)

[学习 FastAPI](./fastapi.md)

这样文档就能互相跳转，适合用在文档网站、GitHub 项目、课程和本地知识库里。

资料链接

回到自己的 README.md，在学习计划后加入 [Python 官网](https://www.python.org/)。预览中应显示“Python 官网”链接，点击后应跳转到对应网站。这里用的是网址；上面的 ./python.md 和 ./fastapi.md 则表示同目录下的文件。

4.6 图片

图片语法机制与相对路径引用

插入图片的写法和链接很像，只是在前面多一个 !：

![图片说明](图片地址)

例如：

![Python Logo](./images/python.png)

对照着记就行：

text

链接：
[文字](地址)

图片：
![说明](地址)

图片路径

图片地址是相对于 Markdown 文件的位置。比如：

![示例](./images/demo.png)

文件里保存的只是路径：

text

./images/demo.png

图片本身仍是单独的文件：

text

demo.png

所以课程目录可能长这样：

text

course/
├── chapter01.md
├── chapter02.md
└── images/
    ├── demo01.png
    └── demo02.png

Markdown 文件里记着图片路径，图片文件本身另行保存。

路径检查

沿用这个相对路径规则。假设文件结构是：

text

docs/
├── chapter01.md
└── images/
    └── python.png

那么 chapter01.md 可以这样引用：

![Python](./images/python.png)

路径写错了，比如：

![Python](./python.png)

预览就可能找不到图片。图片显示失败时，先检查路径，再看语法。

替代文本

图片语法里的第二部分是图片说明：

![Python Logo](./python.png)

text

Python Logo

这就是替代文本。它会在图片加载失败时提供说明，也能帮助屏幕阅读器和搜索引擎理解图片内容，所以尽量写得具体些。比如不要留空：

![](./architecture.png)

可以写成：

![系统整体架构](./architecture.png)

图片预览

继续完善 README.md：在文件旁新建 images/ 文件夹，把一张自己的学习计划截图保存为 images/plan.png，再加入：

![Python 学习计划截图](./images/plan.png)

预览中应显示图片。如果只看到替代文本或破图标记，先检查文件名、扩展名和相对路径；Markdown 只记录路径，不会把图片自动存进文档。

4.7 引用

引用语法形态与嵌套语义场景

行首加 > 就能创建引用：

> 学习编程最重要的是实践。

可以用来引用原话或材料，也常用来突出一条补充说明：

> 注意：删除数据库之前，请先备份数据。

严格来说，> 的语义是引用；普通提醒在支持的工具里可以使用专门的提示组件。

多行与嵌套

同一条引用可以分成几行，中间留空行还能分段：

> Markdown 是一种轻量级标记语言。
>
> 它使用简单符号表达文档结构。

引用里还可以再嵌一层：

> 第一层引用
>
>> 第二层引用

一般嵌一层就够了，套太多层不容易读。

4.8 代码

代码展示体系：行内标记与围栏代码块

正文里出现函数名、文件名、命令、参数、变量或类名时，通常可以用反引号标出来：

例如：

使用 `print()` 输出内容。

可以显示为：

使用 print() 输出内容。

再例如：

创建一个名为 `main.py` 的文件。

或者：

执行 `python main.py` 启动程序。

这些行内代码写法在技术文档里很常见。

字面内容

文件名、安装命令、函数名和参数等字面内容，通常用行内代码标出：

`main.py`

`pip install fastapi`

`print()`

`user_name`

`FastAPI`

`--reload`

它们都是程序或配置里需要按原样输入的内容。比如：

使用 `uvicorn main:app --reload` 启动开发服务器。

这样读者能一眼分清说明文字和需要输入的命令。

围栏代码块

多行代码要用代码块，别挤在行内：

python

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def index():
    return {"message": "Hello"}

Markdown 通常用三个反引号把它围起来：

```python
from fastapi import FastAPI

app = FastAPI()
```

这种写法叫围栏代码块。

语言标识

在代码块的开头标上语言名称：

text

```python

这里的 python 告诉渲染器，代码使用 Python 语法。

这样支持语法高亮的工具就可以按照 Python 规则显示。

JavaScript 也可以这样标注：

```javascript
console.log("Hello")
```

命令行代码则可以标成 bash：

```bash
pip install fastapi
```

常见语言标识包括：

text

python
javascript
html
css
bash
json
yaml
sql

写技术文档时，尽量标明语言，支持语法高亮的工具才能按对应规则显示。

纯文本代码块

不写语言名称时，代码块仍会原样显示。比如也可以用它展示：

```text
project/
├── app/
├── docs/
└── README.md
```

也可以画简单的文本流程：

```text
用户
 ↓
FastAPI
 ↓
数据库
```

文件结构、命令输出、目录树和 ASCII 图等不需要语法高亮的内容。

选用原则

简单记：

text

一句话中的代码
↓
行内代码

例如：

运行 `python main.py`。

多行完整代码则放进代码块：

text

多行代码
↓
代码块

例如：

```python
def add(a, b):
    return a + b
```

程序示例

在 README.md 中也加上“第一个程序”小节：

## 第一个程序

创建 `hello.py`，输入：

```python
print("Hello, Python!")
```

保存后查看预览：代码应独立成块，hello.py 则显示为行内代码。

4.9 分隔线

分隔线语义定位与排版规范

三个短横线可以单独占一行，表示分隔线：

---

也有工具接受三个星号或三个下划线：

***

或者：

___

建议在同一篇文档里统一写成三个短横线：

---

只有内容阶段明显变化、确实需要一个醒目的断点时，才用分隔线。

使用边界

例如：

第一段

---

第二段

---

第三段

---

第四段

普通段落之间频繁加分隔线，会把文章切得很碎。多数时候：

text

标题
+
空行

就足以把结构分清楚。

4.10 综合示例

把刚学的语法放到一份笔记里试试。

README.md 综合案例语法协作蓝图

把前面逐步完成的学习笔记整理成这样：

# Python 学习笔记

Python 是一种 **简单易学** 的编程语言。

我会记录每周计划和遇到的问题。

## 本周计划

- 安装 Python
- 写第一个程序
- 记录遇到的问题

## Python 的特点

Python 具有以下特点：

- 语法简洁；
- 生态丰富；
- 应用范围广。

![Python 学习计划截图](./images/plan.png)

更多信息可以访问 [Python 官网](https://www.python.org/)。

## 第一个程序

创建一个名为 `hello.py` 的文件：

```python
print("Hello, Python!")
```

然后执行：

```bash
python hello.py
```

> 如果命令无法执行，请先确认 Python 是否已经正确安装。

---

## 接下来学习什么

接下来可以继续学习：

1. 变量；
2. 条件判断；
3. 循环；
4. 函数。

先把内容保存为 README.md，保留自己改过的学习计划，并确认同目录下有 images/plan.png。再把代码块中的程序保存为 hello.py，在 Python 3.12 环境中运行 python hello.py，应该看到 Hello, Python!。最后打开预览，逐项看看标题、强调、列表、链接、图片、代码和引用是否符合预期；图片没显示时，先检查相对路径。

源码与预览

编辑器里写的是 Markdown 源码，例如：

## Python 的特点

- 简单
- 易学

渲染器读取后，会把它显示成：

text

Python 的特点

• 简单
• 易学

整个过程可以概括为：

text

Markdown 源码
     ↓
Markdown 渲染器
     ↓
最终页面

GitHub、Typora、Obsidian 和 VitePress 的字体、颜色、间距可能不同，但标题、列表、代码和引用这些结构通常都还在。

渲染差异

这一章学的是核心语法，但不同工具支持的功能并不完全一样。有的还支持：

自动识别网址；
支持删除线；
支持表格；
支持任务列表；
支持 LaTeX；
支持 Mermaid。

也有工具不支持这些扩展。可以把关系简单看成：

text

Markdown 核心语法
        ↓
各种 Markdown 实现
        ↓
各自增加扩展

本章学习的内容属于最基础、最值得优先掌握的一层。

后续章节会专门讨论不同 Markdown 实现之间的区别。

4.11 写作规范

语法会用了，再养成几条写作习惯，后续维护会轻松不少。

工程级写作规范与反模式红绿对照

标题层级

推荐：

# 标题

## 小节

### 子小节

不推荐：

# 标题

#### 子小节

段落空行

推荐：

第一段。

第二段。

留一个空行，源码看起来也更清楚。

列表标记

比如整篇文章都用短横线：

- 项目一
- 项目二

别在文档里来回混用：

text

-
*
+

字面内容

例如：

使用 `pip` 安装依赖。

比不加标记的写法：

使用 pip 安装依赖。

更醒目。

代码块语言

推荐：

```python
print("Hello")
```

而不是：

```
print("Hello")
```

标上语言名称后，支持语法高亮的工具就能按对应语言显示。

图片替代文本

推荐：

![FastAPI 项目目录结构](./images/project.png)

而不是：

![](./images/project.png)

语义与排版

Markdown 用来标记内容结构，不是拿来凑视觉效果。比如：

### 这里字太大了

别因为三级标题字体好看，就把普通正文写成标题。同理：

> 普通正文

也别为了灰色背景，把大段普通内容都写成引用。先判断内容是什么，再挑语法：

text

这是什么内容？
↓
选择对应 Markdown 语法

不要只想着：

text

我想让它长什么样？
↓
随便挑一种看起来好看的语法

这和前面说的“内容与表现分离”是一个意思。

语法速查

忘了写法时可以查这份速记：

# 一级标题

## 二级标题

**粗体**

*斜体*

- 无序列表

1. 有序列表

[链接](https://example.com)

![图片](image.png)

> 引用

`行内代码`

以及代码块：

```python
print("Hello")
```

这些写法能覆盖大多数日常需求。Markdown 不用靠默写来学，能用它把内容结构说明白就行。

4.12 小结

核心语法全景矩阵与思维跃迁罗盘

这一章用标题、段落、强调、列表、链接、图片、引用和代码，把一份学习笔记逐步写完整。记住，符号只是标记；先想清楚内容的结构，再选对应的写法。

下一章接着学几种常见扩展：

表格；
任务列表；
删除线；
数学公式；
Mermaid；
HTML。

这些功能并不全部属于最基础的 Markdown，但在 GitHub、Typora、Obsidian、VitePress 等工具中非常常见。

第四章 Markdown 核心语法 ​

4.1 标题 ​

标题层级 ​

4.2 段落与换行 ​

空行分段 ​

段内换行 ​

笔记预览 ​

4.3 强调 ​

4.4 列表 ​

有序列表 ​

嵌套列表 ​

学习计划 ​

4.5 链接 ​

本地链接 ​

资料链接 ​

4.6 图片 ​

图片路径 ​

替代文本 ​

图片预览 ​

4.7 引用 ​

多行与嵌套 ​

4.8 代码 ​

围栏代码块 ​

语言标识 ​

程序示例 ​

4.9 分隔线 ​

4.10 综合示例 ​

源码与预览 ​

4.11 写作规范 ​

语义与排版 ​

语法速查 ​

4.12 小结 ​

第四章 Markdown 核心语法

4.1 标题

标题层级

4.2 段落与换行

空行分段

段内换行

笔记预览

4.3 强调

4.4 列表

有序列表

嵌套列表

学习计划

4.5 链接

本地链接

资料链接

4.6 图片

图片路径

替代文本

图片预览

4.7 引用

多行与嵌套

4.8 代码

围栏代码块

语言标识

程序示例

4.9 分隔线

4.10 综合示例

源码与预览

4.11 写作规范

语义与排版

语法速查

4.12 小结