声明:原文版权属于 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 地址也适用于此特性。)
becomes
将被渲染为:
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.