技术文档撰写规范与 Markdown 排版美化速查表

良好的技术排版能够大幅降低读者的阅读心智负担。无论是在写个人笔记、GitHub 仓库的 README.md，还是编写微服务接口文档，遵守一套优雅统一的格式法则都是极客基本素养的体现。

一、中文与西文混排：“盘古之白”法则

• 中英文之间保留一个半角空格：例如“使用 Python 脚本处理数据”，而非“使用Python脚本处理数据”。
• 中文与阿拉伯数字之间保留空格：例如“支持 10 种格式解析”，而非“支持10种格式解析”。
• 英文专有名词严格区分大小写：例如 GitHub、Node.js、TypeScript、iOS、Nginx，严禁写成全小写或随意的驼峰。

二、标点符号使用习惯

• 中文句子一律使用全角标点符号（，。！？：；“”‘’）。
• 当提到代码、方法名、文件名、CLI 指令时，必须使用行内代码反引号包裹（如 config.json），包裹后与前后中文字符建议保持自然间隙。

三、代码块标注语言（语法高亮的基础）

严禁使用空语言标签的反引号！务必指明具体的语言标示符，以方便 Markdown 渲染器或语法高亮引擎正确着色：

```bash
# 声明为 bash / sh
sudo systemctl restart nginx
```

```json
{
  "project": "ucncn",
  "version": "1.0.0"
}
```

四、警示框与呼应引用

在 GitHub Flavored Markdown (GFM) 中，推荐使用规范的 Alert 语法：

> [!NOTE]
> 记录普通说明或背景细节。

> [!WARNING]
> 记录破坏性改动或需要重点关注的安全风险。