外观
Markdown 写作指南
约 1060 字
Markdown 是现在写技术文档的通用语。好处是纯文本，任何编辑器都能打开， 不用担心格式跑偏；学会常用语法半小时，但能顺顺当当写成一篇干净文章， 还得讲究点工作流。这篇前半部分查语法，后半部分讲我自己的写法。
一、标题
# 一级标题（一篇文章一般只有一个，就是文章标题）
## 二级标题
### 三级标题
#### 四级标题建议：层级别跳，## 下面直接蹦到 #### 读起来会断层。 另外大部分博客系统会自己渲染标题，你在正文里手写一个 # 文章名 是多余的。
二、强调
**加粗** 和 *斜体* 和 ~~删除线~~
`行内代码` 也很常用我的习惯：加粗只给真正要强调的词，一篇三五个就够。满篇加粗等于没加粗。 行内代码用反引号包起来，写文件名、命令、参数名时用它，专业感+1。
三、列表
无序列表：
- 第一项
- 第二项
- 缩进两项变成子项有序列表：
1. 第一步
2. 第二步任务列表（GitHub、VS Code、多数博客都支持）：
- [x] 学会标题
- [x] 学会列表
- [ ] 学会表格（看下一节）写教程类文章时，任务列表当 checklist 很好用。
四、链接和图片
[链接文字](https://example.com)
图片那个方括号里是 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，链接发出去像中毒。
写作节奏
- 先列小标题骨架，想到什么点就先写个
## 占位； - 往骨架里填肉，顺序无所谓，想到哪写到哪；
- 通读一遍，删废话（我通常能删掉两成）；
- 放一天再看一遍，还觉得顺，发。
几个坚持
- 命令必须真跑过才往上写，跑不通的写明坑；
- 软件写版本号，明年回头看才知道过没过期；
- 不写「众所周知」「不难发现」—— 对读者来说，都众所周知了还看你文章干嘛。
小结
Markdown 语法就上面这些，覆盖 95% 的场景。剩下的（脚注、定义列表、 数学公式）等真用到了再查也不迟。写作工具链越简单越好 —— 我的流程就是 VS Code 加 Git，三年没换过，够用。