GitHub 风格的 Markdown 语法

[译] GitHub 风格的 Markdown 语法

Original: GitHub Flavored Markdown - GitHub Help

Translated by: cssmagic

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

GitHub uses what we're calling "GitHub Flavored Markdown" (GFM) for messages, issues, and comments. It differs from standard Markdown (SM) in a few significant ways and adds some additional functionality.

GitHub 使用一种被称为“GitHub 风格的 Markdown 语法”（GFM）来书写版本注释、Issue 和评论。它和标准 Markdown 语法（SM）相比，存在一些值得注意的差异，并且增加了一些额外功能。

If you're not already familiar with Markdown, you should spend 15 minutes and go over the excellent Markdown Syntax Guide at Daring Fireball.

如果你对 Markdown 还不是很熟悉，那就应该花 15 分钟到 Daring Fireball 去复习一下这个精彩的 Markdown 语法指南。（译注：本文末尾提供了简体中文版的 Markdown 教程。）

If you prefer to learn by example, see the following source and result:

如果你更愿意通过案例来学习，则不妨看看下列源码和渲染结果的对照：

Tip: On Markdown-enabled portions of the site, press m on your keyboard to display a cheat sheet.

提示：在站内所有可用 Markdown 的场合，按 m 键可以显示快捷帮助。

Differences from traditional Markdown

与传统 Markdown 的差异

Newlines

换行

The biggest difference that GFM introduces is in the handling of linebreaks. With SM you can hard wrap paragraphs of text and they will be combined into a single paragraph. We find this to be the cause of a huge number of unintentional formatting errors. GFM treats newlines in paragraph-like content as real line breaks, which is probably what you intended.

GFM 引入的最大差异就是对换行的处理。在 SM 语法中，即使在一段文本中插入硬回车，这些文本仍然会被合并为一个段落。我们发现，这个特性导致了大量非预期的格式化错误。GFM 会把段落内容中的换行视为真正的换行，而这很可能正是你所期望的。

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

Multiple underscores in words

单词中的多个下划线

It is not reasonable to italicize just part of a word, especially when you're dealing with code and names often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words.

没有理由只把一个单词的 一部分 显示为斜体，尤其是当你在处理代码和那些经常出现多个下划线的名称时。因此，GFM 将忽略单词中的多个下划线。

perform_complicated_task

do_this_and_do_that_and_another_thing

becomes

将被渲染为：

perform_complicated_task
do_this_and_do_that_and_another_thing

URL autolinking

链接自动识别

GFM will autolink standard URLs, so if you want to link to a URL (instead of setting link text), you can simply enter the URL and it will be turned into a link to that URL.

GFM 将自动为标准的 URL 加链接，所以如果你只想链接到一个 URL（而不想设置链接文字），那你简单地输入这个 URL 就可以，它将被自动转换为一个链接。（译注：Email 地址也适用于此特性。）

Fenced code blocks

围栏式代码块

Markdown converts text with four spaces at the front of each line to code blocks. GFM supports that, but we also support fenced blocks. Just wrap your code blocks in ``` and you won't need to indent manually to trigger a code block.

Markdown 会把每行前面空四格的文本转换为代码块。GFM 也支持这种语法，同时，我们还支持围栏式代码块。只要把你的代码块包裹在 ``` 之间，你就不需要通过无休止的缩进来标记代码块了。

If you are indenting your code blocks with spaces, keep in mind that code within lists needs to be indented eight times in order to be properly marked as a code block.

如果你使用空格来缩进代码块，请留意列表中的代码块需要缩进 8 个空格，以确保它会被正确地标记为代码块。

Syntax highlighting

语法着色

We take code blocks a step further and add syntax highlighting if you request it. In your fenced block, add an optional language identifier and we'll run it through syntax highlighting. For example, to syntax highlight Ruby code:

我们在处理代码块方面更进一步，你可以为代码码指定语法着色效果。在围栏式代码块中，你可以指定一个可选的语言标识符，然后我们就可以为它启用语法着色了。举个例子，这样可以为一段 Ruby 代码着色：

```ruby

require 'redcarpet'

markdown = Redcarpet.new("Hello World!")

puts markdown.to_html

```

We use Linguist to perform language detection and syntax highlighting. You can find out which keywords are valid by perusing the languages YAML file.

我们使用 Linguist 来进行语言识别和语法着色。你可以在语言 YAML 文件中查证哪些语言标识符是有效的。

Task Lists

任务清单

Further, 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> supported

- [x] list syntax required (any unordered or ordered list supported)

- [x] this is a complete item

- [ ] this is an incomplete item

- [x] 支持 @提到某人、#引用、[链接]()、**格式化** 和 <del>标签</del> 等语法

- [x] 需要使用列表语法来激活（无序或有序列表均可）

- [x] 这是一个已完成项目

- [ ] 这是一个未完成项目

This feature is enabled for Issue and Pull Request descriptions, and comments. Task lists are also available in Gist comments, as well as Gist Markdown files. In those contexts, the task lists are rendered with checkboxes that you can check on and off.

这个特性会在 Issue 和 Pull Request 的描述和评论中启用。任务清单同样可用于 Gist 的评论和 Markdown 格式的 Gist。在这些场合，任务清单将渲染出复选框，供你勾选或清除。

See the Task Lists blog post for more details.

详情参见关于任务清单的博文。

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 will filter 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 then hit enter or tab 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 result set is 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 emoji suggestions. The list will filter as you type, so once you find the emoji you're looking for, just hit tab or enter to complete the highlighted result.

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

Issue autocompletion

Issue 的自动补全

Typing # will bring up a list of Issue and Pull Request suggestions. Type a number or any text to filter the list, then hit tab or enter to complete the highlighted result.

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

Zen Mode (fullscreen) writing

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

Zen Mode allows you to go fullscreen with your writing. You'll find the Zen Mode button on comment, issue, and pull request forms across the site.

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

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

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

Zen Mode offers you two themes to choose from, light or dark. You can change which theme you are using with the switcher at the top right of the window.

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

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

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

References

事件引用

Certain references are auto-linked:

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

* SHA: 16c999e8c71134401a78d4d46435517b2271d6ac

* User@SHA: mojombo@16c999e8c71134401a78d4d46435517b2271d6ac

* User/Project@SHA: mojombo/github-flavored-markdown@16c999e8c71134401a78d4d46435517b2271d6ac

* #Num: #1

* User#Num: mojombo#1

* User/Project#Num: mojombo/github-flavored-markdown#1

becomes

将被渲染为：

SHA: 16c999e
User@SHA: mojombo@16c999e
User/Project@SHA: mojombo/github-flavored-markdown@16c999e
#Num: #1
User#Num: mojombo#1
User/Project#Num: mojombo/github-flavored-markdown#1

Code

实现

The newline and underscore modification code can be seen in below.

关于换行与下划线的差异实现可参见这个 Gist。

If you find a bug in the rendering, please contact support and let us know.

如果你发现了渲染方面的 bug，请联系支持团队让我们知道。

译者后记

GitHub 的这篇文档组织得不是很有条理，也存在一些笔误（~~已联系支持团队~~ 原文已修正）。

在本文开头提到的案例中，源码和渲染结果并不完全匹配，只能作为有限的参考。此问题已反馈，支持团队也已回复确认，但暂未修复。

水果	单价	数量
苹果	3.00	2
香蕉	2.00	4

GitHub Flavored Markdown

GitHub uses "GitHub Flavored Markdown," or GFM, across the site--in issues, comments, and pull requests. It differs from standard Markdown (SM) in a few significant ways, and adds some additional functionality.

If you're not already familiar with Markdown, take a look at Markdown Basics. If you'd like to know more about features that are available in issues, comments, and pull request descriptions, such as task lists, read Writing on GitHub.

Differences from traditional Markdown

Multiple underscores in words

Where Markdown transforms underscores (_) into italics, GFM ignores underscores in words, like this:

wow_great_stuff
do_this_and_do_that_and_another_thing.

This allows code and names with multiple underscores to render properly. To emphasize a portion of a word, use asterisks (*).

URL autolinking

GFM will autolink standard URLs, so if you want to link to a URL (instead of setting link text), you can simply enter the URL and it will be turned into a link to that URL.

http://example.com

becomes

http://example.com

Strikethrough

GFM adds syntax to create strikethrough text, which is missing from standard Markdown.

~~Mistaken text.~~

becomes

~~Mistaken text.~~

Fenced code blocks

Standard Markdown converts text with four spaces at the beginning of each line into a code block; GFM also supports fenced blocks. Just wrap your code in ``` (as shown below) and you won't need to indent it by four spaces. Note that although fenced code blocks don't have to be preceded by a blank line—unlike indented code blocks—we recommend placing a blank line before them to make the raw Markdown easier to read.

Here's an example:

```

function test() {

console.log("notice the blank line before this function?");

}

```

Keep in mind that, within lists, you must indent non-fenced code blocks eight spaces to render them properly.

Syntax highlighting

Code blocks can be taken a step further by adding syntax highlighting. In your fenced block, add an optional language identifier and we'll run it through syntax highlighting. For example, to syntax highlight Ruby code:

```ruby

require 'redcarpet'

markdown = Redcarpet.new("Hello World!")

puts markdown.to_html

```

We use Linguist to perform language detection and syntax highlighting. You can find out which keywords are valid by perusing the languages YAML file.

Tables

You can create tables by assembling a list of words and dividing them with hyphens - (for the first row), and then separating each column with a pipe |:

First Header | Second Header

------------- | -------------

Content Cell | Content Cell

For aesthetic purposes, you can also add extra pipes on the ends:

| First Header | Second Header |

| ------------- | ------------- |

| Content Cell | Content Cell |

Note that the dashes at the top don't need to match the length of the header text exactly:

| Name | Description |

| ------------- | ----------- |

| Help | Display the help window.|

| Close | Closes a window |

You can also include inline Markdown such as links, bold, italics, or strikethrough:

| Name | Description |

| ------------- | ----------- |

| Help | ~~Display the~~ help window.|

| Close | _Closes_ a window |

Finally, by including colons : within the header row, you can define text to be left-aligned, right-aligned, or center-aligned:

| Left-Aligned | Center Aligned | Right Aligned |

| :------------ |:---------------:| -----:|

| col 3 is | some wordy text | $1600 |

| col 2 is | centered | $12 |

| zebra stripes | are neat | $1 |

A colon on the left-most side indicates a left-aligned column; a colon on the right-most side indicates a right-aligned column; a colon on both sides indicates a center-aligned column.

HTML

You can use a subset of HTML within your READMEs, issues, and pull requests.

A full list of our supported tags and attributes can be found in the README for github/markup.