miss sym sset 段落 projects more comment allow scrip

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:

如果你更願意通過案例來學習，則不妨看看下列源碼和渲染結果的對照：

• Source
• 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 的這篇文檔組織得不是很有條理，也存在一些筆誤（已聯系支持團隊 原文已修正）。

在本文開頭提到的案例中，源碼和渲染結果並不完全匹配，只能作為有限的參考。此問題已反饋，支持團隊也已回復確認，但暫未修復。

推薦閱讀

• Markdown 語法說明（簡體中文版）

---

原文版本：2013-07-07 （由於官方 GFM 文檔的組織方式發生了較大變動，本文將不再隨之改動，重要的功能變化將在評論區補充。）

---

? Creative Commons BY-NC-ND 3.0 | 我要訂閱 | 我要捐助

Emoji 代號速查： http://www.emoji-cheat-sheet.com/

GFM現在支持表格了。

表格

你可以使用若幹列文字並於第一行下面用轉折號-分開它們，然後用管道符|隔開每一列：

First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell

為了看上去美觀，你也可以在兩端加上額外的管道符：

| First Header | Second Header | | ------------- | ------------- | | Content Cell | Content Cell | | Content Cell | Content Cell |

註意頂部的虛線不需要準確匹配表頭文本的長度：

| Name | Description | | ------------- | ----------- | | Help | Display the help window.| | Close | Closes a window |

你也可以在其中包括內聯Markdown元素，比如鏈接，加粗，斜體或刪除

| Name | Description | | ------------- | ----------- | | Help | ~~Display the~~ help window.| | Close | _Closes_ a window |

最後，通過在表頭行加入冒號:，你可以決定文本是左對齊，右對齊，還是居中：

| Left-Aligned | Center Aligned | Right Aligned | | :------------ |:---------------:| -----:| | col 3 is | some wordy text | $1600 | | col 2 is | centered | $12 | | zebra stripes | are neat | $1 |

一個在最左邊的冒號表示一個左對齊的列；一個在最右邊的冒號表示一個右對齊的列；兩邊都有的冒號表示一個居中的列。

最後（這裏不再是譯文了），加上我自己的一個示範：

水果	單價	數量
蘋果	3.00	2
香蕉	2.00	4

註意表格要另隔開一個空行。

GitHub Flavored Markdown

• mac
• windows
• linux
• all

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

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

Further reading

• "Writing on GitHub"

http://jbt.github.io/markdown-editor/ 在線編輯器

來源： <https://github.com/cssmagic/blog/issues/13>

GitHub 風格的 Markdown 語法