[译] GitHub 风格的 Markdown 语法

[cssmagic]

[译] GitHub 风格的 Markdown 语法

• Original: GitHub Flavored Markdown - GitHub Help
• Translated by: @cssmagic

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

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.

GitHub 全站支持 “GitHub 风格的 Markdown 语法”（简称 GFM），你可以用它来书写 issue、pull request（以下简称 “PR”）和各种评论。它和标准 Markdown 语法（SM）相比，存在一些值得注意的差异，并且增加了一些额外功能。

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.

如果你对 Markdown 还不是很熟悉，可以先看一眼 Markdown 语法基础。如果你想了解在书写 issue、评论和 PR 描述时有哪些技巧（比如任务清单这样的高级功能），你应该读一下 GitHub 上的书写方式。

Differences from traditional Markdown

与传统 Markdown 的差异

Multiple underscores in words

单词中的多个下划线

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

Markdown 会把所有成对的下划线（_）转换为斜体，但 GFM 不会处理单词内的那些下划线，比如这些：

• 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.

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

http://example.com

becomes

将被渲染为：

http://example.com

Strikethrough

删除线

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

GFM 增加了删除线语法，补上了标准 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.

标准 Markdown 会把每行前面空四格的文本块转换为代码块；GFM 同时还支持围栏式代码块。只要把你的代码块包裹在 ````` 之间就行了（如下所示），你再也不需要通过无休止的缩进来标记代码块了。请注意，虽然围栏式代码块语法并不需要在头部插入空行（缩进式代码块语法是需要的），但我们仍然建议你留出空行，因为这样可以令 Markdown 源码的可读性更好。

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.

请留意，列表中的代码块需要缩进 8 个空格，才会被正确地渲染。

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 代码着色：

```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 文件 中查证哪些语言标识符是有效的。

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
Content Cell  | Content Cell

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

出于美观的考虑，你也可以在表格的两端都加上竖杠：

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| 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:

同时，你也可以在单元格内使用那些行内 Markdown 语法，比如加链接、加粗、加斜体或加删除线等等：

| 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.

在 README、issue 和 PR 中，你还可以使用有限的一些 HTML 语法。

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

关于可用的标签和属性有哪些，你可以在 github/markup 这个项目中找到一份完整的清单。

---

Further reading

• Writing on GitHub

相关阅读

• Markdown 语法基础

---

原文版本：2015-07-20 （如果原文已更新，请提醒我。）

[Fengcoder]

get

[fondadam]

First Header	Second Header
Content Cell	Content Cell
Content Cell	Content Cell

[nstflecher]

谢谢啦