[译] GitHub 上的书写方式

声明：原文版权属于 GitHub。中文翻译并非官方文档，仅供参考。

在 issue、评论和 pull request（以下简称 “PR”）的描述中，我们可以用 “GitHub 风格的 Markdown 语法” 来编写富文本；此外，GitHub 还提供了一些额外的功能，让我们的书写更加方便。

语法

换行

GitHub 上的书写方式与传统 Markdown 相比，有一个最大的不同——我们改变了处理换行的方式。在原始的 Markdown 语法中，如果我们把一段文本用硬回车打断成多行，它们仍然会被合并为一个连续的段落。但我们发现，这个特性导致了大量非预期的格式化错误。在评论中，GitHub 会把段落内容中的换行视为真正的换行，而这通常正是你所期望的。

下面这个段落被一个换行符分隔成了两个短语：

Roses are red
Violets are blue

将被渲染为：

Roses are red
Violets are blue

（译注：注意，只有在评论中才具有这种行为。所谓 “评论”，似乎是指所有非代码提交产生的内容，比如 issue、PR 的描述文字，以及针对 issue、PR、commit 发表的评论等等。在其它场合下，如果需要产生硬回车，需要在行末使用两个空格。）

任务清单

列表可以被转换为 “任务清单”，只需要为列表项的开头加上 [ ] 或 [x] 即可（分别表示未完成和已完成）。

- [x] 支持 @提到某人、#引用、[链接]()、**格式化** 和 <del>HTML 标签</del> 等语法
- [x] 需要使用列表语法来激活（无序或有序列表均可）
- [x] 这是一个已完成项目
- [ ] 这是一个未完成项目

在所有评论和 Markdown 文件中，任务清单都会渲染出复选框。在 GitHub 站内，这些复选框都可以通过勾选和取消勾选来切换完成状态。

任务清单还可以嵌套，以便更好地组织任务：

- [ ] 一个大工程
  - [ ] 第一项子任务 #1234
  - [ ] 接下来的子任务 #4321
  - [ ] 最后一项子任务 cc @mention
- [ ] 一项单独的任务

任务清单的嵌套层级是没有限制的，不过我们建议你最多只嵌套一层或两层；如果你的任务清单需要嵌套更多的层数，则意味着应该把它分解为多个独立的清单。

事件引用

引用特定的 GitHub 事件将会自动创建链接：

* SHA: a5c3785ed8d6a35868bc169f07e40e889087fd2e
* User@SHA: jlord@a5c3785ed8d6a35868bc169f07e40e889087fd2e
* User/Repository@SHA: jlord/sheetsee.js@a5c3785ed8d6a35868bc169f07e40e889087fd2e
* #Num: #26
* GH-Num: GH-26
* User#Num: jlord#26
* User/Repository#Num: jlord/sheetsee.js#26

将被渲染为：

• SHA: a5c3785
• User@SHA: jlord@a5c3785
• User/Repository@SHA: jlord/sheetsee.js@a5c3785
• #Num: #26
• GH-Num: GH-26
• User#Num: jlord#26
• User/Repository#Num: jlord/sheetsee.js#26

便民功能

快速引用

按下键盘的 r 键将为当前的 Issue 或 Pull Request 添加评论。在按下 r 键之前，你在讨论区中选中的任何文本都将自动以一个块级引用的形式插入到你的评论中。

@ 提到人名或团队名时的自动补全

按下 @ 符号将弹出一个列表，列出这个项目相关的人或团队。这个列表会随着你的输入不断匹配筛选，因此一旦你在列表中发现了你要找的人名或团队名，你就可以用方向键来选中它，然后按回车或 tab 键来补全。对于团队来说，只需要输入 @组织名/团队名，那么团队内的所有成员都将收到提醒。

自动补全的匹配范围仅限制在当前仓库的贡献者以及当前讨论的参与者，因此它并不是一个全局性的搜索。它和文件查找器使用相同的模糊筛选算法，并且同时适用于用户名和全名。

详情参见关于 @ 提到 “用户” 和 “团队” 时自动补全的博文。

Emoji 表情符号的自动补全

按下 : 将会弹出一个表情符号的建议列表。这个列表会随着你的输入不断匹配筛选，因此一旦在列表中发现了你要找的表情符号，你就可以按 tab 或回车键来补全当前高亮的那一项。在 emoji-cheat-sheet.com 可以查阅所有可用的表情符号。

Issue 的自动补全

按下 # 将会弹出一个 issue 和 PR 建议列表。输入数字或文本可以不断筛选这个列表，然后按 tab 或回车键可以补全当前高亮的那一项。

禅意模式（全屏书写模式）

禅意模式允许你以全屏模式进行书写。在站内的评论、issue 和 PR 表单中，你都可以找到禅意模式按钮。

在创建或编辑文件时，你也可以在文件框顶部找到禅意模式按钮。

禅意模式提供了两种主题可供选择，浅色版和深色版。你可以用窗口右上角的切换按钮来更换当前主题。

（题图作者：Ben Scholzen @ Flickr）