Markdown：写给嵌入式开发者的文档语言

我们为什么要认真学 Markdown

很多人觉得 Markdown 就是"写笔记用的那种标记语法"，随便会点 # 和 ** 就够了。可一旦你开始正经做嵌入式开发，会发现 Markdown 是你天天在写的东西：每个驱动模块要配一份 README、Kconfig 选项要写 help 说明、设备树节点要有注释、给开源项目提 PR 要填描述、issue 要描述复现步骤——这些全都是 Markdown。写得规范，别人（包括未来的你）一眼就能看懂；写得乱，寄存器表对不齐、代码块套代码块渲染崩掉、中文加粗莫名其面失效，沟通成本直线上升。

这一篇我们不是罗列语法，而是把每个语法点放到嵌入式真实场景里讲——你会看到怎么用表格画引脚映射、用代码块写 Kconfig 片段、用任务列表跟驱动开发进度。我们把最常用的几样吃透，最后拼出一份完整的驱动 README。

标题：文档的骨架

在文字前面加 # 就能建标题，# 越多级别越小，一共六级。写法是这样：

markdown

# 一级标题(最大)
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题(最小)

渲染出来就是下面这样层层递进的样子：

一级标题(最大)

二级标题

三级标题

四级标题

五级标题

六级标题(最小)

唯一要记住的细节是 # 后面必须空一格再写标题文字，不然有些渲染器不认。一份文档通常只用一个一级标题（当文章名），正文从二级开始往下分。

文字样式：让文字有重点

加粗用 **文字**，斜体用 *文字*，加粗又斜体用 ***文字***，删除线用 ~~文字~~，都是成对符号把目标包起来：

markdown

这是**加粗的文字**
这是*斜体文字*
这是***加粗又斜体***
这是~~要删除的文字~~

渲染出来：这是 加粗的文字，这是 斜体文字，这是 加粗又斜体，这是 ~~要删除的文字~~。

⚠️ 注意一个坑：__（双下划线）加粗、_（单下划线）斜体、~~ 删除线，这三种两侧紧贴中文或数字时都不会生效——它们要求"词边界"，而汉字在规则里算字母。解决办法很简单，前后留个空格就行，比如 这是 __加粗__ 文字；加粗和斜体也可以干脆改用 ** 和 *，星号形式没这个限制。

列表：整理信息和步骤

无序列表用 -、+ 或 * 开头加空格，三者等价，习惯上统一用 -：

markdown

- 苹果
- 香蕉
- 橙子

苹果
香蕉
橙子

有序列表用 1.、2. 开头，写驱动步骤、烧录流程时最常用：

markdown

1. 初始化 SPI 主机
2. 拉低 CS，读 ID 寄存器
3. 调用读取接口

初始化 SPI 主机
拉低 CS，读 ID 寄存器
调用读取接口

列表还能嵌套，用缩进（两到四个空格）表示从属关系，画引脚分组、外设层级时很好用：

markdown

1. 水果
   - 苹果
   - 香蕉
2. 蔬菜
   - 萝卜
     - 红萝卜
     - 白萝卜

水果
- 苹果
- 香蕉
蔬菜
- 萝卜
  - 红萝卜
  - 白萝卜

链接和图片

链接的格式是 [显示文字](地址)，图片多一个感叹号 ![描述](地址)：

markdown

[数据手册](https://www.bosch-sensortec.com/)
![芯片照片](https://example.com/chip.jpg)

渲染出来：数据手册。图片的描述文字会在图片加载失败时显示，也算一种无障碍信息，别偷懒留空。

引用：强调或转述

用 > 开头表示引用，可以连续多行；多个 > 叠在一起就是嵌套引用：

markdown

> 这是一段重要的提醒
> 可以写多行

> 鲁迅说过:
> "我没说过这句话。"

这是一段重要的提醒可以写多行

鲁迅说过: "我没说过这句话。"

在教程和文档里，引用块特别适合放"注意""提示""背景补充"这类跟正文区分开的内容。

代码：行内与代码块

行内代码用一个反引号包裹，代码块用三个反引号围起来、还能在开头标语言触发高亮。下面这个例子本身就在演示"代码块里再放一个代码块"，所以外层我们用了四个反引号来围：

写法示例：

markdown

```python
def hello():
    print("Hello, Markdown!")
```

显示效果：

python

def hello():
    print("Hello, Markdown!")

写嵌入式文档时，代码块几乎天天用——贴一段 Kconfig、一段设备树、一段 Makefile，标对语言就能高亮。一个容易踩的坑：当代码块本身的内容里就含三个反引号（比如你在教别人写代码块），外层围栏得用更多的反引号（四个或波浪线），否则提前闭合、渲染就乱了——上面那个例子就是这个用意。

分隔线

三个或更多 -、*、_ 单独成行，就渲染成一条分隔线，用来在视觉上切分大段内容：

markdown

---
***
___

渲染效果就是下面这一条：

表格：画寄存器、引脚、参数映射

表格是嵌入式文档里出场率极高的东西——引脚映射、寄存器位定义、外设参数对比，全靠它。用 | 分列、- 分隔表头和内容：

markdown

| 信号 | MCU 引脚 | 说明 |
| ---- | ---- | ---- |
| VCC  | 3.3V | 供电 |
| SCK  | PA5  | SPI 时钟 |
| CS   | PB0  | 片选，低有效 |

信号	MCU 引脚	说明
VCC	3.3V	供电
SCK	PA5	SPI 时钟
CS	PB0	片选，低有效

表头下面那行的 : 还能控制对齐：:--- 左对齐、:---: 居中、---: 右对齐，数字列习惯右对齐、文字列左对齐。

任务列表：跟开发进度

任务列表用 - [ ]（未完成）和 - [x]（已完成），写驱动的开发进度、issue 的检查清单特别合适：

markdown

- [x] 寄存器读写
- [x] 温度/气压换算
- [ ] 低功耗模式
- [ ] 软件滤波

[x] 寄存器读写
[x] 温度/气压换算
[ ] 低功耗模式
[ ] 软件滤波

GitHub 的 issue 和 PR 原生支持任务列表勾选，你直接在网页上点方框就能更新状态。

实战：给一个嵌入式驱动写 README

我们把上面这些语法拼到一起，写一份真实场景的文档——为某颗 SPI 气压传感器（BMP280）写驱动 README。比起"我的学习笔记"，这个才是你以后每个驱动模块都要配的东西。下面这段就是一个 README.md 的完整写法，外层用四个反引号围，因为它内部还嵌着一个 Kconfig 代码块：

markdown

# BMP280 气压传感器驱动

适用于 SPI 总线的 Bosch BMP280 驱动，提供温度/气压读取接口。

## 引脚与接线

| 信号 | MCU 引脚 | 说明 |
| --- | --- | --- |
| VCC  | 3.3V     | 供电，**严禁接 5V** |
| GND  | GND      | 地 |
| SCK  | PA5      | SPI 时钟 |
| MOSI | PA7      | 主出从入 |
| MISO | PA6      | 主入从出 |
| CS   | PB0      | 片选，低有效 |

## 使用步骤

1. 初始化 SPI 主机（模式 0，速率 ≤ 10MHz）。
2. 拉低 CS，读芯片 ID 寄存器（应返回 `0x58`）。
3. 调用 `bmp280_read()` 取一组数据。

## Kconfig 片段

```kconfig
config BMP280
    bool "BMP280 pressure sensor driver"
    depends on SPI
    help
      启用 Bosch BMP280 气压/温度传感器驱动。
```

## 开发进度

- [x] 寄存器读写
- [x] 温度/气压换算
- [ ] 低功耗模式
- [ ] 软件滤波

## 参考

- [BMP280 datasheet](https://www.bosch-sensortec.com/)

渲染出来，它就是一篇带标题、表格、有序列表、任务列表、Kconfig 代码块和超链接的完整文档。这一份案例一次把标题、表格、有序列表、任务列表、代码块、链接六种最常用的语法都用上了，哪个不会就回头翻对应小节。

几个常用小技巧

段落之间空一行才是真换行；行尾加两个空格再回车是强制换行（同段内）。要显示特殊符号本身（比如想显示一个真的 * 而不是斜体标记），在前面加反斜杠转义，\* 就显示成 *。记忆上，# 是标题、* 是强调、- 是列表、> 是引用、反引号是代码、[] 是链接和任务——记住这几个，绝大多数文档就够写了。

小结

Markdown 的语法本身不复杂，难的是用得规范、用得贴场景。我们这一篇把标题、文字样式、列表、链接图片、引用、代码、分隔线、表格、任务列表过了一遍，重点记三件事：代码块里再放代码块时外层围栏要加长；__/_/~~ 紧贴中文不生效、记得留空格或改用星号；表格和任务列表是嵌入式文档的高频武器。最后那份 BMP280 驱动 README 就是把这些拼起来的样子，你可以拿它当自己驱动模块文档的模板。

下一站

文档会写了，接下来把代码版本管好——尤其是想给内核、驱动这类用邮件协作的开源项目提 patch，Git 还有一套跟 GitHub PR 不一样的玩法。

下一卷：Git：内核 / 驱动协作视角

Markdown：写给嵌入式开发者的文档语言 ​

我们为什么要认真学 Markdown ​

标题：文档的骨架 ​

一级标题(最大) ​

二级标题 ​

三级标题 ​

四级标题 ​

五级标题 ​

六级标题(最小) ​

文字样式：让文字有重点 ​

列表：整理信息和步骤 ​

链接和图片 ​

引用：强调或转述 ​

代码：行内与代码块 ​

分隔线 ​

表格：画寄存器、引脚、参数映射 ​

任务列表：跟开发进度 ​

实战：给一个嵌入式驱动写 README ​

几个常用小技巧 ​

小结 ​

下一站 ​

Markdown：写给嵌入式开发者的文档语言

我们为什么要认真学 Markdown

标题：文档的骨架

一级标题(最大)

二级标题

三级标题

四级标题

五级标题

六级标题(最小)

文字样式：让文字有重点

列表：整理信息和步骤

链接和图片

引用：强调或转述

代码：行内与代码块

分隔线

表格：画寄存器、引脚、参数映射

任务列表：跟开发进度

实战：给一个嵌入式驱动写 README

几个常用小技巧

小结

下一站