GitHub 上的书写方式

Question

Issues, comments, and pull request descriptions are written using GitHub Flavored Markdown along with some additional features to make writing content on GitHub easy.

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

Markup 语法

Newlines 换行

The biggest difference with writing on GitHub is the way we handle linebreaks. With Markdown, you can hard wrap paragraphs of text to have them combine into a single paragraph. We find this causes a huge number of unintentional formatting errors. In comments, GitHub treats newlines in paragraph-like content as real line breaks, which is usually what you intended.

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

The next paragraph contains two phrases separated by a single newline character:

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

Roses are red
Violets are blue

becomes

将被渲染为：

Roses are red
Violets are blue

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

Task lists 任务清单

Lists can be turned into task lists by prefacing list items with [ ] or [x] (incomplete or complete, respectively).

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

- [x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> are supported
- [x] list syntax is required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] this is an incomplete item

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

Task lists render with checkboxes in all comments and Markdown files. Select or unselect these checkboxes to mark them as complete or incomplete across GitHub.

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

Task lists can be nested to better structure your tasks:

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

- [ ] a bigger project
  - [ ] first subtask #1234
  - [ ] follow up subtask #4321
  - [ ] final subtask cc @mention
- [ ] a separate task

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

Task lists can be nested to arbitrary depths, though we recommend nesting at most once or twice; more complicated tasks should be broken out into separate lists.

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

References 事件引用

Certain references are auto-linked:

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

* 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

becomes

将被渲染为：

• 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

Features 便民功能

Quick quoting 快速引用

Typing r on your keyboard lets you reply to the current issue or pull request with a comment. Any text you select within the discussion thread before pressing r will be added to your comment automatically and formatted as a blockquote.

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

Name and Team @mentions autocomplete @ 提到人名或团队名时的自动补全

Typing an @ symbol will bring up a list of people or teams on a project. The list filters as you type, so once you find the name of the person or team you are looking for, you can use the arrow keys to select it and hit either tab or enter to complete the name. For teams, just enter the @organization/team-name and all members of that team will get subscribed to the issue.

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

The autocomplete results are restricted to repository collaborators and any other participants on the thread, so it's not a full global search. It uses the same fuzzy filter as the file finder and works for both usernames and full names.

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

Check out the blog posts for more information about @mention autocompletes for users and teams.

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

Emoji autocomplete Emoji 表情符号的自动补全

Typing : will bring up a list of suggested emoji. The list will filter as you type, so once you find the emoji you're looking for, press Tab or Enter to complete the highlighted result. For a full list of available emoji, check out emoji-cheat-sheet.com.

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

Issue autocompletion Issue 的自动补全

Typing # will bring up a list of suggested Issues and Pull Requests. Type a number or some text to filter the list, then hit either tab or enter to complete the highlighted result.

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

Zen Mode (fullscreen) writing 禅意模式（全屏书写模式）

Zen Mode allows you to write markdown in fullscreen mode. You'll find the Zen Mode button on comment, issue, and pull request forms across the site.

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

You can also use it when creating and editing files by using the Zen Mode button above the file box.

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

Zen Mode comes with both a light and a dark theme. You can change your theme using the switcher at the top right of the window.

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

Check out the blog post for more information about Zen writing mode.

详情参见 关于禅意模式的博文。

---

See also

• Markdown Basics
• GitHub Flavored Markdown

相关阅读

• Markdown 语法基础
• GitHub 风格的 Markdown 语法