深色模式
文档写作规范
摘要：格式混乱的文档会显著拖慢阅读速度，尤其在事故现场。本文统一标题层级、命令块、表格与名词写法，并给出可用 CI 执行的格式检查脚本。
适用环境
bash
cd docs
command -v python3 >/dev/null && echo "可用脚本检查"
ls -1 *.md | head1
2
3
2
3
操作步骤
第 1 步：固定文档骨架
bash
cat > skeleton.md <<'EOF'
---
title: <标题>
description: <一句话摘要，用于搜索>
date: 2026-10-09
tags: [<标签>]
---
# 标题（与 front matter 一致）
> 摘要：2-3 句，说明解决什么问题
## 适用环境
## 操作步骤
## 验证
## 常见坑
## 参考资料
EOF1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
第 2 步：标题层级规则
bash
cat > headings.md <<'EOF'
- 一级标题（#）全篇仅一个，即文档标题
- 二级标题（##）表示大段：适用环境/操作步骤/验证/常见坑/参考资料
- 三级标题（###）表示步骤：第 1 步、第 2 步
- 禁止跳级：# 后直接 ###
EOF1
2
3
4
5
6
2
3
4
5
6
第 3 步：命令块规范
bash
# 每条命令都要能直接复制执行，注释说明期望输出
kubectl -n prod get deploy demo # 期望：READY 与期望副本一致1
2
2
bash
cat > cmd-rules.md <<'EOF'
1. 命令块必须标注语言（bash/yaml/json）
2. 不给终端渲染不出的长行，必要时用 \ 换行
3. 危险命令前加说明，不藏在块中间
4. 不粘贴包含真实密钥、内网 IP、用户数据的输出
EOF1
2
3
4
5
6
2
3
4
5
6
第 4 步：名词与格式统一
bash
cat > glossary.md <<'EOF'
| 统一写法 | 禁止写法 |
| --- | --- |
| Kubernetes / K8s | k8s、kubernetes（句首除外） |
| Pod、Deployment | pod、deploy（混用） |
| 回滚 | 回退、rollback（混用） |
| Sev1 | sev1、P0（混用） |
EOF1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
第 5 步：用脚本自动检查
bash
cat > check-docs.sh <<'EOF'
#!/usr/bin/env bash
for f in "$@"; do
# 一级标题数量
h1=$(grep -c '^# ' "$f")
# 是否跳级（## 之后直接 #### ）
skip=$(grep -c '^#### ' "$f")
# 是否有摘要与参考资料
grep -q '^> 摘要' "$f" && abs=1 || abs=0
grep -q '^## 参考资料' "$f" && ref=1 || ref=0
echo "$f h1=$h1 h4=$skip 摘要=$abs 参考资料=$ref"
done
EOF
chmod +x check-docs.sh && ./check-docs.sh *.md1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
验证
bash
# 1. 所有文档骨架一致
./check-docs.sh *.md | grep -v 'h1=1 摘要=1 参考资料=1'
# 2. 代码块都标注语言
grep -n '^```$' *.md | wc -l
# 3. 无未闭合代码块（数量应为偶数）
for f in *.md; do echo "$f $(grep -c '^```' "$f")"; done1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
常见坑
中英文之间不留空格
"重启pod" 可读性差。中文与英文/数字之间加空格，标点用全角。
复制真实终端输出含敏感信息
日志里常带内网地址、token、用户 ID。粘贴前必须脱敏。
把未验证的命令写进文档
未跑过的命令可能参数错误，值班人照抄会引发二次故障。命令必须在实际环境验证后再入库。