Markdown 是现在写技术文档的通用语。好处是纯文本，任何编辑器都能打开， 不用担心格式跑偏；学会常用语法半小时，但能顺顺当当写成一篇干净文章， 还得讲究点工作流。这篇前半部分查语法，后半部分讲我自己的写法。

一、标题

# 一级标题（一篇文章一般只有一个，就是文章标题）
## 二级标题
### 三级标题
#### 四级标题

建议：层级别跳，## 下面直接蹦到 #### 读起来会断层。 另外大部分博客系统会自己渲染标题，你在正文里手写一个 # 文章名 是多余的。

二、强调

**加粗** 和 *斜体* 和 ~~删除线~~
`行内代码` 也很常用

我的习惯：加粗只给真正要强调的词，一篇三五个就够。满篇加粗等于没加粗。 行内代码用反引号包起来，写文件名、命令、参数名时用它，专业感+1。

三、列表

无序列表：

- 第一项
- 第二项
  - 缩进两项变成子项

有序列表：

1. 第一步
2. 第二步

任务列表（GitHub、VS Code、多数博客都支持）：

- [x] 学会标题
- [x] 学会列表
- [ ] 学会表格（看下一节）

写教程类文章时，任务列表当 checklist 很好用。

四、链接和图片

[链接文字](https://example.com)
![图片描述](./images/photo.png)

图片那个方括号里是 alt 文字，图裂了的时候显示，读屏软件也读它。 别空着，写句话描述图是什么。

图片放哪是个现实问题。我的做法：文章配图放文章同级的 images/ 文件夹， 相对路径引用；全站通用的图（logo、头像）放站点 public 目录，绝对路径引用。

五、代码块

三个反引号包起来，后面跟语言名，会有语法高亮：

```bash
git clone https://github.com/example/repo.git
```

渲染出来长这样：

git clone https://github.com/example/repo.git

写教程给命令，语言写 bash（或 sh、shell）；写配置文件写 json、 yaml；写代码写对应的 js、ts、python。不写语言名就没高亮， 黑底白字一大坨，很伤眼睛。

六、表格

| 命令 | 作用 |
| --- | --- |
| git add | 放进暂存区 |
| git commit | 提交 |

表格适合放「速查」类内容，别拿表格凑字数 —— 大段散文拆成表格反而难读。

七、引用

> 这是一段引用。
> 可以换行继续。

引用适合放名言、警告、题外话。技术文档里也常用来放注意事项：

> ⚠️ 这条命令会删数据，执行前确认当前目录。

八、分割线

三个及以上的减号或星号：

---

长文章里用来分段换气。不过我这篇用得不多 —— 标题本身就是分隔。

我的写作工作流

工具就两样：VS Code 写字，Git 管版本。

文件组织

项目根目录/
├── posts/               # 文章都放这
│   ├── 2026-10-git-guide/
│   │   ├── index.md     # 正文
│   │   └── images/      # 这篇的配图
│   └── ...

一篇文章一个文件夹，图片跟文章走。将来搬家、归档，整个文件夹一拷贝就走。

命名

文件名用英文小写加连字符：git-quickstart.md。别用空格和中文 —— URL 里会变成一堆 %E4%B8%AD，链接发出去像中毒。

写作节奏

1. 先列小标题骨架，想到什么点就先写个 ## 占位；
2. 往骨架里填肉，顺序无所谓，想到哪写到哪；
3. 通读一遍，删废话（我通常能删掉两成）；
4. 放一天再看一遍，还觉得顺，发。

几个坚持

• 命令必须真跑过才往上写，跑不通的写明坑；
• 软件写版本号，明年回头看才知道过没过期；
• 不写「众所周知」「不难发现」—— 对读者来说，都众所周知了还看你文章干嘛。

小结

Markdown 语法就上面这些，覆盖 95% 的场景。剩下的（脚注、定义列表、 数学公式）等真用到了再查也不迟。写作工具链越简单越好 —— 我的流程就是 VS Code 加 Git，三年没换过，够用。