[譯] GitHub 風格的 Markdown 語法

2020-06-16 17:01:38

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 這個專案中找到一份完整的清單。