GitHub上README写法暨GFM语法解读，gitoschina也适用

自从开始玩GitHub以来，就愈来愈感受它有爱。最近对它的README.md文件颇为感兴趣。便写下这贴，帮助更多的还不会编写README文件的同窗们。

README文件后缀名为md。md是markdown的缩写，markdown是一种编辑博客的语言。用惯了可视化的博客编辑器（好比CSDN博客，囧），这种编程式的博客编辑方案着实让人眼前一亮。不过GitHub支持的语法在标准markdown语法的基础上作了修改，称为Github Flavored Markdown，简称GFM。可不是GFW呀。

————————————————————————————

我在GitHub上为本文建的一个仓库“test”，供你们查看代码即具体效果：https://github.com/guodongxiaren/test 

本仓库README文件持续更新，新的知识点可能不会更新到博文中。首先强烈建议一条，不要用360或搜狗浏览器访问GitHub网站，你会发现此时网站上不少按钮都不可用。。建议使用火狐或谷歌浏览器访问GitHub

————————————————————————————

开始编辑README

打开你的GitHub的某个项目，咱们能够直接在线编辑你的README文件，若是你已经有了这个文件，则在文件目录中直接点击它，若是你尚未这个文件那么点击项目名称右边的一个按钮，来添加新文件：

而后你就打开了编辑页面，编辑区的左上角有填写文件名的区域，注意加上后缀.md

若是你原本就有这个文件要从新编辑它的话，那么在点击了文件目录中的该文件后，在上方有工具栏，选择Edit

而后滚动屏幕到下面，若是是新文件会有一个Commit new file的按钮，若没有内容是不能点击的。若是是旧文件重修编辑，那么这个按钮显示的是 Commit changes

//顺便吐槽一句若是是360或搜狗浏览器的话，这个按钮是永远都没法点击的，囧。。

先随便写的东西把这个新文件提交，而后再点击 Edit 从新打开它。你会发现编辑区左上角有了变化。

默认选中Code，即咱们的编辑模式。若点击 Preview（预览）就能实时显示当前的显示效果了。

好了，下面正式开始编辑这个文件

关于标题

规范的README文件开头都写上一个标题，这被称为大标题。

大标题  
====

在文本下面加上 等于号 = ，那么上方的文本就变成了大标题。等于号的个数无限制，但必定要大于0个哦。。

比大标题低一级的是中标题，也就是显示出来比大标题小点。

中标题  
-------

在文本下面加上 下划线 - ，那么上方的文本就变成了中标题，一样的 下划线个数无限制。

除此以外，你也会发现大，中标题下面都有一条横线，没错这就是 = 和 - 的显示结果。

若是你只输入了等于号=，但其上方无文字，那么就只会显示一条直线。若是上方有了文字，但你又只想显示一条横线，而不想把上方的文字转义成大标题的话，那么你就要在等于号=和文字直接补一个空行。

补空行：是很经常使用的用法，当你不想上下两个不一样的布局方式交错到一块儿的时候，就要在两种布局之间补一个空行。

若是你只输入了短横线（减号）-，其上方无文字，那么要显示直线，必需要写三个减号以上。不过与等于号的显示效果不一样，它显示出来时虚线而不是实线。同减号做用相同的还有星号*和下划线_，一样的这二者符号也要写三个以上才能显示一条虚横线。

除此之外，关于标题还有等级表示法，分为六个等级，显示的文本大小依次减少。不一样等级之间是以井号  #  的个数来标识的。一级标题有一个 #，二级标题有两个# ，以此类推。

#一级标题  
##二级标题  
###三级标题  
####四级标题  
#####五级标题  
######六级标题

注意井号#和标题名称要并排写做一行，显示效果如图：

实际上，前文所述的大标题和中标题是分别和一级标题和二级标题对应的。即大标题大小和一级标题相同，中标题大小和二级标题相同。

显示文本

普通文本

直接输入的文字就是普通文本。须要注意的是要换行的时候不能直接经过回车来换行，须要使用<br>(或者<br/>)。也就是html里面的标签。事实上，markdown支持一些html标签，你能够试试。固然若是你彻底使用html来写的话，就丧失意义了，毕竟markdown并不是专门作前端的，然而仅实现通常效果的话，它会比html写起来要简洁得多得多啦。

这是一段普通的文本，  
直接回车不能换行，<br>  
要使用\<br>

注意第三行的<br>前加了反斜杠 \ 。目的就是像其余语言那样实现转义，也就是 <  的转义。

效果如图：

此外，要显示一个超连接的话，就直接输入这个连接的URL就行了。显示出来会自动变成可连接的形式的。

显示空格的小Tip

默认的文本行首空格都会被忽略的，可是若是你想用空格来排一下版的话怎么办呢，有个小技巧，那就是把你的输入法由半角改为全角就OK啦。

单行文本

使用两个Tab符实现单行文本。

            Hello,你们好，我是果冻虾仁。

 

注意前面有两个Tab。在GitHub上单行文本显示效果如图：

多行文本

多行文本和单行文本殊途同归，只要在每行行首加两个Tab

        欢迎到访  
        很高兴见到您  
        祝您，早上好，中午好，下午好，晚安

部分文字的高亮

若是你想使一段话中部分文字高亮显示，来起到突出强调的做用，那么能够把它用 `  ` 包围起来。注意这不是单引号，而是Tab上方，数字1左边的按键（注意使用英文输入法）。

Thank `You` . Please `Call` Me `Coder`

文字超连接

给一段文字加入超连接的格式是这样的 [ 要显示的文字 ]( 连接的地址 )。好比：

[个人博客](http://my.oschina.net/hnuweiwei)

显示效果：

你还能够给他加上一个鼠标悬停显示的文本。

[个人博客](http://my.oschina.net/hnuweiwei "悬停显示")

即在URL以后 用双引号括起来一个字符串。一样要注意这里是英文双引号。

插入符号

圆点符

• 这是一个圆点符

• 这也是一个圆点符

上面这段的圆点是CSDN博客编辑器里面的符号列表。写文章在列出条目时常常用到。在GitHub的markdown语法里也支持使用圆点符。编辑的时候使用的是星号 *

* 昵称：果冻虾仁  
* 别名：隔壁老王  
* 英文名：Jelly

要注意的是星号* 后面要有一个空格。不然显示为普通星号。上文的显示效果如图：

此外还有二级圆点和三级圆点。就是多加一个Tab。

* 编程语言  
    * 脚本语言  
        * Python

第二行一个Tab，第三行两个Tab。这样用来表示层级结构就更清晰了吧，看效果：

若是你以为三级的结构还不够表达清楚的话，咱们能够试着换一种形式，请看字符包围

缩进

缩进的含义是很容易理解的。。

>数据结构  
>>树  
>>>二叉树  
>>>>平衡二叉树  
>>>>>满二叉树

显示效果：

固然比这个更通常的用法是这样。经常能在书籍里面看到的效果，好比引用别人的文章。直接看效果。

具体这个“缩进”的用法。你们本身摸索吧。

插入图片

来源于网络的图片

网上有不少README插入图片的教程了，经我本身屡次测试呢，发现可使用的最简单，最基本的语法是：

![](http://www.baidu.com/img/bdlogo.gif)

即 叹号! + 方括号[ ] + 括号( ) 其中叹号里是图片的URL。

若是不加叹号! ,就会变成普通文本baidu了。

在方括号里能够加入一些 标识性的信息，好比

![baidu](http://www.baidu.com/img/bdlogo.gif)

这个方括号里的baidu并不会对图像显示形成任何改动，若是你想达到鼠标悬停显示提示信息，那么能够仿照前面介绍的文本中的方法，就是这样：

![baidu](http://www.baidu.com/img/bdlogo.gif "百度logo")

在URL后面，加一个双引号包围的字符串，显示效果如图：

GitHub仓库里的图片

有时候咱们想显示一个GitHub仓库(或者说项目)里的图片而不是一张其余来源网络图片，由于其余来源的URL极可能会失效。那么如何显示一个GitHub项目里的图片呢？

其实与上面的格式基本一致的，所不一样的就是括号里的URL该怎么写。

    https://github.com/ 你的用户名 / 你的项目名 / raw / 分支名 / 存放图片的文件夹 / 该文件夹下的图片

这样一目了然了吧。好比：

![](https://github.com/guodongxiaren/ImageCache/raw/master/Logo/foryou.gif)

我在GitHub上的用户名guodongxiaren；有一个项目ImageCache；raw表示原数据的意思吧，不用管它；主分支master；项目里有一个文件夹Logo；Logo文件夹下有一张图片foryou.gif

给图片加上超连接

若是你想使图片带有超连接的功能，即点击一个图片进入一个指定的网页。那么能够这样写：

[![baidu]](http://baidu.com)  
[baidu]:http://www.baidu.com/img/bdlogo.gif "百度Logo"

这两句和前面的写法差别较大，可是也极易模仿着写出，就不过多介绍了。只需注意上下文中的 baidu 是你本身起的标识的名称，能够随意，可是必定要保证上下两行的 标识 是一致的。

这样就能实现 点击图片进入网页的功能了。

插入代码片断

咱们须要在代码的上一行和下一行用` `` 标记。``` 不是三个单引号，而是数字1左边，Tab键上面的键。要实现语法高亮那么只要在 ``` 以后加上你的编程语言便可（忽略大小写）。c++语言能够写成c++也能够是cpp。看代码：

实际显示效果

[题外话]在GitHub上用Gist写日记吧

看了这么多markdown的语法，你必定不知足于仅仅写一个README文件了，开始跃跃欲试想实际用markdown语法来编写博客或文章了吧。的确，网上也有依托或者支持markdown语法的博客。可是呢，更方便的是，你能够借助GitHub自己就有的一个功能——Gist。

Gist是以文件为单位的，不是以项目为单位的。并且与普通的GitHub上建的仓库不一样，Gist是private的哦。普通的项目默认都是public的，要想弄成private貌似还要交钱的样子。既然是private那么用来写写日记，是极好的。

GitHub网页的顶部有：

点进去:

这就是你能够编辑的私有文件，它不只支持Text文本，还支持各类编程语言呢！固然也包括markdown。输入文件名：

最后保存，选中 Create Secret Gist 就是私有的喽。

其余参考网址：

https://help.github.com/articles/github-flavored-markdown

https://www.imququ.com/post/use-markdown-on-my-blog.html

http://files.cnblogs.com/chengn/MarkDown%E8%BD%BB%E9%87%8F%E7%BA%A7%E6%A0%87%E8%AE%B0%E8%AF%AD%E8%A8%80.pdf

TEST
===========================
This README.md is used to testing all kinds of syntax of GitHub Flavored Markdown.
---------------------------
###　　　　　　　　　　　　Author:Jelly
###　　　　　　　　　 E-mail:wlyrics@163.com

===========================



##<a name="index"/>目录
* [横线](#line)
* [标题](#title)
* [显示文本](#text)
    * 普通文本
    * 单行文本
    * 多行文本
    * 部分文字高亮
* [超连接](#link) 
    * 文字超连接
        *  连接外部URL
        *  连接本仓库里的URL
        *  锚点
    * [图片超连接](#piclink)
* [显示图片](#pic)
    * 来源于网络的图片
    * GitHub仓库中的图片
* [列表](#dot)
* [符号包围](#symbol)
* [代码高亮](#code)

<a name="line"/>
##***、---、___显示虚横线
***
---
___



<a name="title"/>
#一级标题
##二级标题
###三级标题
####四级标题
#####五级标题
######六级标题


##<a name="text"/>显示文本
###普通文本
这是一段普通的文本，
直接回车不能换行，<br>
要使用\<br>

  或者在回车之后，再加上两个空格。完成这种换行效果。
###单行文本
    Hello,你们好，我是果冻虾仁。
###多行文本
    欢迎到访
    很高兴见到您
    祝您，早上好，中午好，下午好，晚安
###部分文字高亮
Thank `You` . Please `Call` Me `Coder`
####高亮功能更适合作一篇文章的tag
例如:<br>
`java` `网络编程` `Socket` `全双工`


##<a name="link"/>文字连接
###连接外部URL
[个人博客](http://blog.csdn.net/guodongxiaren/article/details/23690801 "悬停显示")
###连接本仓库里的URL
[Book](./Book)
###锚点
[点此回到目录](#index)

##<a name="pic"/>显示图片
###来源于网络的图片
![baidu](http://www.baidu.com/img/bdlogo.gif "百度logo")
###GitHub仓库中的图片
![](https://github.com/guodongxiaren/ImageCache/raw/master/Logo/foryou.gif)
###<a name="piclink">给图片加上超连接
[![head]](http://blog.csdn.net/guodongxiaren/article/details/23690801)

##<a name="dot"/>列表
###圆点列表
* 昵称：果冻虾仁
* 别名：隔壁老王
* 英文名：Jelly

###更多圆点
* 编程语言
    * 脚本语言
        * Python

### 复选框列表
- [x] C
- [x] C++
- [x] Java
- [x] Qt
- [x] Android
- [ ] C#
- [ ] .NET

##<a name="symbol"/>缩进
###用于列表
>数据结构
>>树
>>>二叉树
>>>>平衡二叉树
>>>>>满二叉树

###用于引用：
####文本摘自《深刻理解计算机系统》P27
　使人吃惊的是，在哪一种字节顺序是合适的这个问题上，人们表现得很是情绪化。实际上术语“little endian”（小端）和“big endian”（大端）出自Jonathan Swift的《格利佛游记》一书，其中交战的两个派别没法就应该从哪一端打开一个半熟的鸡蛋达成一致。所以，争论沦为关于社会政治的争论。只要选择了一种规则而且始终如一的坚持，其实对于哪一种字节排序的选择都是任意的。
><b>“端”（endian）的起源</b><br>
如下是Jonathan Swift在1726年关于大小端之争历史的描述：<br>
“……下面我要告诉你的是，Lilliput和Blefuscu这两大强国在过去36个月里一直在苦战。战争开始是因为如下的缘由：咱们你们都认为，吃鸡蛋前，原始的方法是打破鸡蛋较大的一端，但是当今的皇帝的祖父小时候吃鸡蛋，一次按古法打鸡蛋时碰巧将一个手指弄破了，所以他的父亲，当时的皇帝，就下了一道敕令，命令全体臣民吃鸡蛋时打破较小的一端，违令者重罚。”


##<a name="code"/>代码高亮
```Java
public static void main(String[]args){} //Java
```
```c
int main(int argc, char *argv[]) //C
```
```Bash
echo "hello GitHub"#Bash
```
```javascript
document.getElementById("myH1").innerHTML="Welcome to my Homepage"; //javascipt
```
```cpp
string &operator+(const string& A,const string& B) //cpp
```
##插入表格
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     |

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