|
| 1 | +--- |
| 2 | +layout: page |
| 3 | +title: GitHub Markdown[翻译] |
| 4 | +category: markdown |
| 5 | +description: markdown syntax |
| 6 | +--- |
| 7 | + |
| 8 | +本文翻译自: |
| 9 | +* <https://help.github.com/articles/markdown-basics/> |
| 10 | +* <https://help.github.com/articles/github-flavored-markdown/> |
| 11 | +* <https://help.github.com/articles/writing-on-github/> |
| 12 | + |
| 13 | +[TOC] |
| 14 | + |
| 15 | +# GitHub Markdown |
| 16 | + |
| 17 | +## 1. Markdown基础知识 |
| 18 | + |
| 19 | +[Markdown][markdown]允许你采用一种方便阅读和方便书写的纯文本格式书写, 而纯文本则会转化成正确的HTML格式用于在GitHub上浏览. |
| 20 | + |
| 21 | +[markdown]: http://daringfireball.net/projects/markdown/syntax#precode |
| 22 | + |
| 23 | +### 段落 |
| 24 | + |
| 25 | +Markdown中的段落只是一行或多行文本之后跟着一个或多个空白行. |
| 26 | + |
| 27 | + On July 2, an alien mothership entered Earth's orbit and deployed several dozen saucer-shaped "destroyer" spacecraft, each 15 miles (24 km) wide. |
| 28 | + |
| 29 | + On July 3, the Black Knights, a squadron of Marine Corps F/A-18 Hornets, participated in an assault on a destroyer near the city of Los Angeles. |
| 30 | + |
| 31 | +### 标题 |
| 32 | + |
| 33 | +你可以通过在你的标题文本之前添加一个或多个`#`符号来创建一个标题. 你所使用`#`的数量将决定标题的尺寸. |
| 34 | + |
| 35 | + # The largest heading (an <h1> tag) |
| 36 | + ## The second largest heading (an <h2> tag) |
| 37 | + … |
| 38 | + ###### The 6th largest heading (an <h6> tag) |
| 39 | + |
| 40 | +### 引用 |
| 41 | + |
| 42 | +你可以通过一个`>`来指示引用. |
| 43 | + |
| 44 | + In the words of Abraham Lincoln: |
| 45 | + |
| 46 | + > Pardon my french |
| 47 | + |
| 48 | +### 文本样式 |
| 49 | + |
| 50 | +你可以是文字**加粗**或*斜体*. |
| 51 | + |
| 52 | + *This text will be italic* |
| 53 | + **This text will be bold** |
| 54 | + |
| 55 | +无论是粗体还是斜体能可以采用一个`*`或一个`_`来围绕文本用于样式. 这使得你如果有需要可以联合起来既粗体有斜体. |
| 56 | + |
| 57 | + **Everyone _must_ attend the meeting at 5 o'clock today.** |
| 58 | + |
| 59 | +### 无序列表 |
| 60 | + |
| 61 | +你可以通过在列表前面添加一个`*`或者一个`-`来产生一个无序列表. |
| 62 | + |
| 63 | + * Item |
| 64 | + * Item |
| 65 | + * Item |
| 66 | + |
| 67 | + - Item |
| 68 | + - Item |
| 69 | + - Item |
| 70 | + |
| 71 | +### 有序列表 |
| 72 | + |
| 73 | +你可以通过在列表前面添加一个数字来产生一个有序列表. |
| 74 | + |
| 75 | +1. Item 1 |
| 76 | +2. Item 2 |
| 77 | +3. Item 3 |
| 78 | + |
| 79 | +### 嵌套列表 |
| 80 | + |
| 81 | +你可以通过这两张方式缩进列表项来产生一个嵌套列表. |
| 82 | + |
| 83 | + 1. Item 1 |
| 84 | + 1. A corollary to the above item. |
| 85 | + 2. Yet another point to consider. |
| 86 | + 2. Item 2 |
| 87 | + * A corollary that does not need to be ordered. |
| 88 | + * This is indented four spaces, because it's two spaces further than the item above. |
| 89 | + * You might want to consider making a new list. |
| 90 | + 3. Item 3 |
| 91 | + |
| 92 | +### Code内联式 |
| 93 | + |
| 94 | +使用单引号(` ` `)把文本格式化成一个特殊的monospace格式. 在引号内的任何文本都如文本本身所示, 不存在其他特殊的格式. |
| 95 | + |
| 96 | + Here's an idea: why don't we take `SuperiorProject` and turn it into `**Reasonable**Project`. |
| 97 | + |
| 98 | +### Code多线式 |
| 99 | + |
| 100 | +你可以使用三个引号(` ``` `)格式化文本, 使文本格式正如其自身块所示. |
| 101 | + |
| 102 | +Check out this neat program I wrote: |
| 103 | + |
| 104 | + ``` |
| 105 | + x = 0 |
| 106 | + x = 2 + 2 |
| 107 | + what is x |
| 108 | + ``` |
| 109 | + |
| 110 | +### 链接 |
| 111 | + |
| 112 | +你可以将用方括号(`[]`)包围链接文本并且用圆括号(`()`)包围链接来产生一个内联链接. |
| 113 | + |
| 114 | +例如, 为了生成一个超链接www.github.com, 并且链接文字是"Visit GitHub!", 那么你需要用Markdown这样写: |
| 115 | + |
| 116 | + [Visit GitHub!](https://www.github.com). |
| 117 | + |
| 118 | +## 2. GFM |
| 119 | + |
| 120 | +GitHub在`issues`,`comments`,和`pull requests`中使用"GitHub Flavored Markdown"或GFM. 与标准Markdown(SM)相比,在一些地方会存在不同,而且增加了一些额外功能. |
| 121 | + |
| 122 | +如果你不是很熟悉Markdown,可以先看看[Markdown Basics][basic].如果你想要了解更多`issues`,`comments`,和`pull requests`相关的特性,例如工作表(task lists),可以阅读[Writing on GitHub][writing]. |
| 123 | + |
| 124 | +### 单词间的下划线 |
| 125 | + |
| 126 | +SM将把下划线(`_`)斜体, 而GFM则是忽略单词间的下划线. |
| 127 | + |
| 128 | +例如: |
| 129 | + > wow_great_stuff |
| 130 | + > do_this_and_do_that_and_another_thing |
| 131 | + |
| 132 | +这样可以使得具有下划线的代码和命名可以正常渲染. 为了强调一个单词的一部分,可以使用星号(`*`). |
| 133 | + |
| 134 | +### URL自动链接 |
| 135 | + |
| 136 | +GFM会自动链接标准URL.所以如果你想要链接一个URL(不是链接文字),你可以简单地输入URL, 而它会被转换成指向URL的一个超链接. |
| 137 | + |
| 138 | + http://example.com |
| 139 | + |
| 140 | +将成为 |
| 141 | + |
| 142 | +http://example.com |
| 143 | + |
| 144 | +### 删除线 |
| 145 | + |
| 146 | +GFM增加了一个语法来产生删除文本,而这个在SM中是没有的. |
| 147 | + |
| 148 | + ~~mistaken text.~~ |
| 149 | + |
| 150 | +将成为 |
| 151 | + |
| 152 | +~~mistaken text.~~ |
| 153 | + |
| 154 | +### 栅栏式代码块(Fenced code blocks) |
| 155 | + |
| 156 | +SM会将每行开头包含四个空格的文本转换成代码块, 而GFM也支持栅栏式代码块. 只需要用` ``` `(如下所示)包围你的代码, 你就可以不需要再缩进四个空格. |
| 157 | + |
| 158 | +注意: 和缩进式代码块不一样, 栅栏式代码块可以不需要之前的空白行,但是我们建议在它们之前放置一个空白行,使得原始的Markdown更容易阅读. |
| 159 | + |
| 160 | + Here's an example: |
| 161 | + |
| 162 | + ``` |
| 163 | + function test() { |
| 164 | + console.log("notice the blank line before this function?"); |
| 165 | + } |
| 166 | + ``` |
| 167 | + |
| 168 | +请记住, 列表内,你必须缩进非栅栏式代码块*8个*空格来正确地渲染. |
| 169 | + |
| 170 | +### 语法高亮 |
| 171 | + |
| 172 | +代码块能够进一步增加语法高亮. 在你的栅栏块里增加一个可选的语言标识符, 接着我们就可以进行代码高亮了. |
| 173 | + |
| 174 | +例如, 为了Ruby代码语法高亮: |
| 175 | + |
| 176 | + ```ruby |
| 177 | + require 'redcarpet' |
| 178 | + markdown = Redcarpet.new("Hello World!") |
| 179 | + puts markdown.to_html |
| 180 | + ``` |
| 181 | + |
| 182 | +我们使用[Linguist][linguist]来进行语言检测和语法高亮. 你可以阅读[语言YAML文件][languages]来找出哪些关键字是正确的. |
| 183 | + |
| 184 | +[linguist]: https://github.com/github/linguist |
| 185 | +[languages]: https://github.com/github/linguist/blob/master/lib/linguist/languages.yml |
| 186 | + |
| 187 | +### 表格 |
| 188 | + |
| 189 | +你可以用连字符`-`(用于第一行)来组装和分隔一些单词来创建列表, 然后用一个管道字符`|`来分隔每一列: |
| 190 | + |
| 191 | + First Header | Second Header |
| 192 | + ------------- | ------------- |
| 193 | + Content Cell | Content Cell |
| 194 | + Content Cell | Content Cell |
| 195 | + |
| 196 | +为了美观的目的,你也可以在两端添加二外的管道字符: |
| 197 | + |
| 198 | + | First Header | Second Header | |
| 199 | + | ------------- | ------------- | |
| 200 | + | Content Cell | Content Cell | |
| 201 | + | Content Cell | Content Cell | |
| 202 | + |
| 203 | +请注意, 在上面的破折号并不需要完全匹配标题文本的长度: |
| 204 | + |
| 205 | + | Name | Description | |
| 206 | + | ------------- | ----------- | |
| 207 | + | Help | Display the help window.| |
| 208 | + | Close | Closes a window | |
| 209 | + |
| 210 | +你也可以包含内联的Markdown, 例如链接, 粗体, 斜体, 或删除线: |
| 211 | + |
| 212 | + | Name | Description | |
| 213 | + | ------------- | ----------- | |
| 214 | + | Help | ~~Display the~~ help window.| |
| 215 | + | Close | _Closes_ a window | |
| 216 | + |
| 217 | +最后,通过标题行内的冒号来定义文本是左对齐, 右对齐或居中对齐: |
| 218 | + |
| 219 | + | Left-Aligned | Center Aligned | Right Aligned | |
| 220 | + | :------------ |:---------------:| -----:| |
| 221 | + | col 3 is | some wordy text | $1600 | |
| 222 | + | col 2 is | centered | $12 | |
| 223 | + | zebra stripes | are neat | $1 | |
| 224 | + |
| 225 | +最左边的一个冒号表明一个左对齐的列; 最右边的一个冒号表明一个右对齐的列; 而两边都有冒号表明一个居中对齐的列. |
| 226 | + |
| 227 | +### HTML |
| 228 | + |
| 229 | +你可以在你的`READMEs`,`issues`和`pull requests`中使用HTML的子集. |
| 230 | + |
| 231 | +一个包含所有我们支持的标签和属性的列表可以在[gitugithub/markup repository][markup]找到. |
| 232 | + |
| 233 | +[markup]: https://github.com/github/markup |
| 234 | + |
| 235 | + |
0 commit comments