嵌入式工程师写技术文档,这几个 Markdown 技巧一定要会

微信：zhenglf5805关注可了解更多的AI工具相关内容。问题或建议，请公众号留言;[如果你觉得文章对你有帮助，欢迎点赞留言]

大家好，我是在深圳做嵌入式开发的工程师奶爸。

做嵌入式开发这些年，我最怕的从来不是调代码、啃几百页芯片手册，而是写项目技术文档。用 Word 排版，换个版本格式全乱；寄存器表格、驱动代码粘来粘去，可读性极差；项目迭代改一次，文档就要重新调一次格式，到了客户交付的时候，文档反而成了最耗时间的活。

最近我用 TRAE 的 Skill 功能，定制了一套嵌入式专属的 Markdown 开发规范文档，今天把我写 STM32 项目文档最高频、最实用的技巧，全部分享给你，看完就能直接复制用。

前言：为什么嵌入式工程师必须学好Markdown？

嵌入式开发的文档工作，天生有这些痛点：

• • 用Word/Excel排版，换个版本就乱版；

• • 驱动代码、调试日志和文档分离，后续找不到对应代码上下文；

• • 无法版本追踪；

• • 跨团队格式错乱、附件断链；

而Markdown完美解决以上问题：

• • 原生兼容Git，版本管理零成本；

• • 语法极简，写文档效率提升50%以上；

• • 全平台兼容；

• • 可无缝嵌入代码、表格、时序图、公式；

• • 一键导出PDF/Word/HTML/公众号格式；

• • 可直接用于AI工具

一、嵌入式文档必备基础语法（精准适配工作场景）

先把最常用的基础语法用对，以下均为嵌入式开发高频使用场景。

1. 标题层级：建立标准化文档结构

严格遵循「1级标题→2级标题→3级标题」的规范。参考之前的文章让您的公众号文章排版更精美，完全免费工具markdown之一：标题+字体

2. 引用块：标注关键注意事项/手册原文

引用块（> 开头）专门用来标注硬件Errata、芯片手册原文、调试红线、勘误说明。

高频使用示例

3. 列表：规范步骤/特性/任务管理

任务列表：用于开发进度、测试用例、待办事项，可直接在GitHub/Gitee渲染进度。

高频使用示例

二、嵌入式工程师专属核心技巧（干货核心）

这部分是本文的重点，看完即可直接落地到你的技术文档中。

技巧1：用表格搞定寄存器/引脚定义，告别Excel乱版

寄存器位定义表、引脚复用表、硬件资源分配表。

技巧2：代码块高阶用法，驱动/调试日志完美呈现

Markdown彻底告别「代码截图无法复制、无法搜索」的痛点。可用代码块如：

```c```diff```python

技巧3：用Mermaid画时序图/框图，纯文本可版本控制

技巧4：LaTeX公式，完美呈现算法/硬件计算

参考之前的文章高效渲染排版AI免费工具markdown：数学公式+流程图+语文注音

技巧 5：文档与工程一体化，链接 / 附件永久有效

推荐的嵌入式工程目录结构

project/├── docs/               // 技术文档目录│   ├── 驱动开发手册.md│   ├── 硬件调试记录.md│   └── 方案设计文档.md├── datasheet/          // 芯片手册目录│   ├── STM32F103xx_datasheet.pdf│   └── AT24C02_datasheet.pdf├── hardware/           // 硬件资料目录│   ├── mainboard_sch.pdf│   └── mainboard_pcb.pdf├── drivers/            // 驱动代码目录├── application/        // 应用代码目录└── tools/              // 工具脚本目录    ├── flash.sh    └── openocd.cfg

文档中的链接写法

### 参考资料- [STM32F103官方datasheet](../datasheet/STM32F103xx_datasheet.pdf)- [USART驱动源码](../drivers/usart.c)

三、嵌入式工程师拿来即用的Markdown模板

以下2个模板覆盖嵌入式开发90%的文档场景，直接复制即可使用。

模板1：芯片外设驱动开发文档模板

驱动外设开发手册.zip

模板2：嵌入式项目README.md模板

嵌入式项目README模板.zip

👉 关注公众号，后台回复【Markdown 模板】，直接领取完整可复制的模板文件

四、嵌入式工程师高频踩坑避坑指南

1. 1. 滥用平台专属语法，跨平台失效

2. 2. 图片用绝对路径，换环境就断链

3. 3. 大段文本不换行，Git对比完全失效

4. 4. 代码块不指定语言，无高亮可读性极差

5. 5. 复杂表格过度合并单元格，渲染乱版

6. 6. 公众号发布样式失效

结尾

Markdown 从来不只是「排版工具」，而是「提升开发效率、规范项目管理、降低团队协同成本」的核心技能。从今天开始，把你的技术文档、项目手册、调试记录，都换成 Markdown 吧。

配合我之前分享的

用 AI 工具 Skill 搞定 STM32 寄存器开发，开发效率直接翻倍

觉得文章对你有帮助，别忘了点赞、在看、转发给身边做嵌入式开发的同事，后续我会分享更多嵌入式开发、AI 提效的实战技巧。