零基础学会技术文档Markdown编写规范
为什么需要技术文档Markdown编写规范
技术文档不只是写清楚流程，排版和结构直接影响阅读效率。
Markdown 作为最流行的轻量标记语言，几乎覆盖所有代码托管平台（GitHub、GitLab）、知识库（Notion、语雀）和静态站（Hexo、VuePress）。
如果一份文档标题层级混乱、代码块没有语法高亮、列表缩进不对，读者很难快速找到关键信息。
下面从零开始，把规范写到每一步。
准备工作：选对的编辑器与预览工具
你不用安装任何额外软件——系统自带的记事本就能写 Markdown，但推荐用 VS Code 或 Typora。
VS Code 免费且支持实时预览，按 Ctrl+Shift+P 搜索“Markdown: Open Preview”就能看到渲染效果。
Typora 所见即所得，适合纯新手。
确认好工具后，新建一个 readme.md 文件，开始练习。
核心语法：标题、列表、代码块怎么写才规范
1. 标题层级要连续
标题用 # 表示，一级标题只出现一次（通常是文档标题），后面按顺序用 ##、###。
不要跳过层级（例如 ## 后直接 ####）。
示例：
# 文档标题
## 第一节
### 1.1 小节
#### 1.1.1 细节2. 列表不要混用符号和缩进
无序列表用 -，有序列表用 1.。同一级列表的缩进必须一致（通常 2 或 4 空格）。
嵌套列表时子项前多缩进两个空格：
- 一级项
- 二级项
- 三级项3. 代码块必须标注语言
行内代码用反引号 ` `，多行代码用三个反引号 ` 包裹，并在起始反引号后写明语言名（如 bash、yaml、python`），这样渲染时才有语法高亮。
错误写法：
ls -la
正确写法：
ls -la
避坑指南：90% 新手会踩的 3 个坑
1. 列表和代码块之间缺少空行
Markdown 中列表后直接接代码块会导致解析错误。在列表项最后一个句号后，多按一次回车，保证代码块前有一个空行。
2. 图片链接使用相对路径时大小写不一致
如果文档和图片放在同一目录，链接写成  时，文件名大小写必须与真实文件一致（Linux 服务器严格区分）。推荐统一使用小写加短横线：./images/screenshot-01.png。
3. 表格中对齐标记 : 放错位置
表格第二行控制对齐：| :--- | :---: | ---: | 分别表示左对齐、居中、右对齐。少写一个冒号可能整个表格渲染失败。
效果验证：用 lint 工具自动检查规范
写完后不要只靠眼力。
推荐使用 markdownlint（VS Code 插件）或命令行工具 markdownlint-cli。
安装后，在项目根目录运行：
# 安装（全局）
npm install -g markdownlint-cli
# 检查当前目录所有 .md 文件
markdownlint *.md它会高亮出缩进错误、标题层级跳跃、行尾空格等问题。
另外可以开启 VS Code 的“保存时自动格式化”功能，在设置中搜索 editor.formatOnSave 并勾选。
最后，把写好的文档用 GitHub 预览或本地浏览器打开，对照常见排版检查一遍：标题层级是否连贯、代码块是否被正确高亮、列表缩进是否对齐。规范不是束缚，而是为了让以后的自己（或接手的人）少花半小时在排版上。
从这篇开始，每次写技术文档都按本文步骤走，一周后你就会形成肌肉记忆。
