Markdown 技术笔记写作与排版指南

写技术笔记时，最常见的问题不是不会用某个符号，而是打开文档以后找不到重点。一段里混着现象、命令和结论，读者要来回翻才能知道下一步该做什么。Markdown 本身只提供少数几种结构，把这几种用稳，笔记就会清楚很多。

本文按 CommonMark ↗ 里稳定的基础语法来写。不同编辑器会加自己的扩展，笔记如果要在网站、文档和代码仓库之间搬来搬去，先用这些基础写法更稳妥。

先定结构，再填内容

一篇能读完的笔记，通常只有四块：

1. 这篇要解决什么问题。
2. 正确做法是什么，按顺序写。
3. 哪些写法看起来对、实际会错。
4. 最后用几句话收回结论。

标题用来标出这四块，不要拿它当装饰。一级标题留给文章题目。正文从二级标题开始，同一层标题讲同一类事情。如果一个小节里又出现了独立的步骤，再往下用三级标题，不要跳级。

标题单独占一行，前后留空行。和上一行粘在一起时，有的渲染器会把它当成普通文字。

把步骤写成列表

操作顺序用有序列表，并列的注意事项用无序列表。列表项尽量写成完整的一句，不要只丢一个词。

1. 把配置保存为 UTF-8。
2. 用检查工具确认括号和引号成对。
3. 再启动使用这份配置的程序。

列表前后也要留空行。少了空行时，列表可能被并进上一段，序号和缩进都会乱。

需要强调的词用一对 **，例如 先备份再覆盖。斜体在中文里辨识度不高，少用。不要整段加粗，加粗多了等于没有重点。

代码和命令单独成块

文件名、命令、配置键放在行内代码里，用一对反引号包住，例如 package.json。超过一行的内容放进围栏代码块，并写上语言名称，方便阅读器着色：

```python
from pathlib import Path
text = Path("app.json").read_text(encoding="utf-8")
```

语言名称写常见的小写名字即可，如 python、json、bash。不确定就留空，不要写一个阅读器不认识的名字。

代码块里再出现三个反引号时，外层改用四个反引号，否则代码块会提前结束。命令如果依赖当前目录，在代码块上面用一句话写明「在项目目录中执行」，不要让读者猜。

链接只放真正有用的地址

正文里需要出处时，用方括号写读者能看懂的文字，圆括号里放地址：

格式说明见 [CommonMark 规范](https://spec.commonmark.org/)。

链接文字写成「点击这里」没有信息量。地址很长时，也不要把整串网址铺在句子中间。本地笔记里的相对链接，例如 [安装说明](./install.md)，换了目录以后可能失效，发布前要点一次确认。

图片同理：![配置文件截图](./config.png)。方括号里写这张图在说什么。纯装饰图可以留空，但说明性的图不要留空，否则读屏工具只能读到「图片」。

常见错误

• 中文和英文标点混着用，列表符号又换成全角，渲染器认不出列表。
• 用 Tab 和空格混着缩进。嵌套列表时，子项前面统一空两格或四格，并在全文保持一致。
• 在 JSON、命令示例里加 Markdown 才有的 > 引用符号，复制出去以后命令无法执行。
• 表格列对不齐就硬排。列数不稳定时，改用列表，比一张挤乱的表更容易读。
• 把整篇笔记放在一个一级标题下面，中间不再分段。读者无法跳着查。

写完以后先只看标题列表：如果标题串起来不能说明这篇笔记的顺序，正文再长也难用。然后再把代码块复制到对应的工具里跑一次，确认围栏没有把命令截断。

小结

Markdown 笔记靠标题分层、列表表顺序、代码块隔离可复制内容、链接给出处。这四样保持空行和层级正确，排版就不会跟内容抢注意力。扩展语法可以以后再加，基础结构稳定之后，换编辑器也不容易乱。