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 |