markdown-formatting

Markdown 格式约定

适用场景

• 编写或编辑任何 Markdown 文档
• 检查正文是否符合换行规范
• 使用插件（scribe、sanctum 等）生成 Markdown

不适用场景

• 编辑代码块、表格或 frontmatter（这些内容有各自的格式规则）
• 不会提交的临时速记

这些约定适用于所有由插件生成或修改的 Markdown 文档。目标是让正文 生成整洁、易于审查的 git 差异，并且在移动设备上易于阅读。

快速参考

编写或编辑 Markdown 正文时：

1. 每行最多 80 个字符，采用混合换行方式（优先在句子或分句边界换行， 而不是随意拆分单词）
2. 每个标题前后都留空行
3. 仅使用 ATX 标题（# Heading，不要使用 setext 下划线）
4. 每个列表前都留空行
5. 如果行内链接会让行长度超过 80 个字符，使用引用式链接

需要换行的内容

以下内容每行最多 80 个字符：

• 段落（连续的正文文本）
• 引用文本（> 后的内容）
• 列表项描述（- 或 1. 后的文本）
• 定义列表中的描述

不需要换行的内容

以下内容绝不能换行或重新排版：

• 表格：以竖线分隔的行保持为单行
• 代码块：围栏式（```）或缩进内容
• 标题：以 # 开头的行
• Frontmatter：--- 或 +++ 之间的 YAML/TOML
• HTML 块：原始 HTML 元素
• 链接定义：[id]: url 引用行
• 图片引用：单独一行的 ![alt](url)
• 单行列表项：适合放在一行内的简短项目符号

换行算法（摘要）

对于每个正文段落：

1. 如果一句话不超过 80 个字符，就保持在一行
2. 如果一句话超过 80 个字符，就在第 80 列前最近的 句子边界（. ! ? ）处换行
3. 如果没有句子边界，就在第 80 列前最近的分句边界 （, ; : ）处换行
4. 如果没有分句边界，就在第 80 列前最近的连词 （and but or ）前换行
5. 如果以上位置都不存在，就在第 80 列前最后一个单词边界处换行
6. 绝不要在反引号包围的文本、链接文本或 URL 中间换行

完整算法及示例请参阅 modules/wrapping-rules.md。

结构规则

标题前后的空行

WRONG:
Some text.
## Heading
More text.

RIGHT:
Some text.

## Heading

More text.

例外：文件的第一行可以是标题，前面无需空行。

仅使用 ATX 标题

WRONG:
Heading
=======

WRONG:
Subheading
----------

RIGHT:
# Heading

RIGHT:
## Subheading

列表前的空行

WRONG:
Some introductory text:
- Item one
- Item two

RIGHT:
Some introductory text:

- Item one
- Item two

长 URL 使用引用式链接

如果行内链接会让行长度超过 80 个字符，请使用引用式语法：

WRONG (line too long):
See the [formatting guide](https://google.github.io/styleguide/docguide/style.html) for details.

RIGHT:
See the [formatting guide][fmt-guide] for details.

[fmt-guide]: https://google.github.io/styleguide/docguide/style.html

将链接定义放在当前章节末尾或文档末尾。同一个 URL 多次出现时， 使用单个共享的引用定义。

不会让行长度超过 80 个字符的短行内链接可以保留：

OK:
See [the guide](https://example.com) for details.

完成标准

• 编辑文件中的所有正文行均不超过 80 个字符；通过运行 awk 'length>80' <file> 验证，正文块中不返回任何匹配项 （不包括表格、代码、标题和 frontmatter）
• 每个标题前后都有空行（文件第一行除外）；不存在 setext 风格的 下划线标题
• 每个列表前都有空行
• 会让行长度超过 80 个字符的行内链接，均已转换为引用式语法， 并在章节末尾或文档末尾添加 URL 定义