09 常见坑与写作规范

这一章是本教程最实用的部分——踩过的坑都在这。

坑 1：符号后面忘了空格

写法	结果
# 标题	✅ 标题
#标题	❌ 普通文字
- 列表	✅ 列表
-列表	❌ 普通文字
> 引用	✅ 引用
>引用	❌ 普通文字（部分平台）

💡 一句话：Markdown 符号后面，永远打一个空格。

坑 2：以为「回车 = 换行」

Markdown 里单个回车只是空格，要空行才是新段落。

第一行
第二行      ← 这两行渲染后连在一起

第三行      ← 空行之后才是新段落

想紧密换行：行尾加 <br>。

坑 3：全角 / 半角符号混用

中文输入法下很容易打出全角符号，它们不会被识别：

错误（全角）	正确（半角）
＃标题	# 标题
－ 列表	- 列表
＞ 引用	> 引用
（说明）	(说明)
｜ 表格 ｜	\| 表格 \|
｀｀code｀｀	`code`
** 粗体**（中文空格）	**粗体**

排查方法：把光标放到符号上左右移动——全角符号占的位置更宽；或者干脆删掉重打一遍（切成英文输入法）。

坑 4：表格缺分隔行

错误：

| 名称 | 版本 |
| Forge | 47.4.23 |

正确：

| 名称 | 版本 |
| --- | --- |
| Forge | 47.4.23 |

坑 5：代码块没闭合 / 嵌套失败

• 开头有三个反引号，结尾必须也有三个，否则后面全变代码。
• 要在代码块里显示代码块，外层用四个反引号。

坑 6：_下划线_ 在词中失效

snake_case_name → 不会变斜体（正确行为）。 要斜体就写 *snake\_case\_name*，或者直接用 * 号：*snake_case_name*。

坑 7：列表嵌套缩进不一致

有人缩 1 格、有人缩 4 格、有人用 Tab → 在不同平台渲染结果不一样。

规范：统一缩 2 个空格（MkDocs / GFM 都稳）。

坑 8：标题层级乱跳

# 文章标题
### 直接跳到三级    ← ❌

规范：# → ## → ### 逐级往下，别跳。文档自动生成的目录、侧栏都依赖层级。

坑 9：图片/链接地址含空格

[文字](我的 文件.md) → 链接断掉。 解决：把空格换成 %20，或把文件名改成用 -/_。

坑 10：以为所有平台都支持

同一份文档发到不同地方可能变形：

内容	GitHub	QQ 聊天	结果
表格	渲染	不渲染	群里成一堆竖线
任务列表	渲染	不渲染	群显示 - [ ]
脚注	渲染	不渲染	群显示 [^1]

💡 发给聊天软件时：用 - 列表 + Emoji 代替表格（本站的群推送就是这么做的）。

中文写作规范（重要）

写中文技术文档时，这些习惯会让文档好看很多：

规则	说明	例子
中英文之间加空格	视觉上更透气	「使用 Java 17 运行」而不是「使用Java17运行」
中文用中文标点	逗号句号引号	「这是说明，请遵守。」
代码/文件名用行内代码	一眼分辨	修改 config.json
专有名词大小写正确	别写错	Forge、KubeJS、MkDocs、GitHub
数字与单位间加空格	规范	8 GB、47.4.23
全角括号转半角	在代码/英文语境里	(1.20.1)
标题不加句号	标题是短语	## 常见坑 ✅
列表句尾标点一致	要么都有句号，要么都没有	—

文档结构规范

一份好的文档通常长这样：

# 标题（一级，只有一个）

一句话说明本文是什么。

## 前置条件
- 需要什么环境 / 版本

## 操作步骤
1. 第一步
2. 第二步

## 常见问题
| 现象 | 解决 |

## 参考链接
- [官方文档](地址)

文件与目录命名

建议	原因
用小写字母 + -：first-forge-mod.md	跨平台安全，URL 好看
别用空格和中文文件名	容易编码出错
用两位数字前缀排序：01-xxx.md	文件列表自然有序（本站就这么干）
图片统一放 assets/images/	好管理、迁移方便

提交前自检清单

• 符号后面都有空格？
• 段落之间都空行了？
• 没有全角符号误用？
• 表格都有分隔行？
• 代码块都闭合了？
• 标题层级没跳级？
• 中英文之间加了空格？
• 预览里看过一遍？

本章练习

1. 故意写一段「全角符号 + 无空格」的错误 Markdown，看它渲染失败。
2. 把它改成规范写法，对比渲染结果。
3. 用上面的自检清单检查你之前写的练习文件。

下一章进入实战：用 MkDocs 搭自己的文档站。