GitHub上README.md教程(copy)
【說明：轉(zhuǎn)載于http://blog.csdn.net/kaitiren/article/details/38513715】
?
最近對它的README.md文件頗為感興趣。便寫下這貼，幫助更多的還不會編寫README文件的同學們。
README文件后綴名為md。md是markdown的縮寫，markdown是一種編輯博客的語言。用慣了可視化的博客編輯器（比如CSDN博客，囧），這種編程式的博客編輯方案著實讓人眼前一亮。不過GitHub支持的語法在標準markdown語法的基礎(chǔ)上做了修改，稱為Github Flavored Markdown，簡稱GFM。可不是GFW呀。
————————————————————————————
我在GitHub上為本文建的一個倉庫“test”，供大家查看代碼即具體效果：https://github.com/guodongxiaren/test?
本倉庫README文件持續(xù)更新，新的知識點可能不會更新到博文中。首先強烈建議一條，不要用360或搜狗瀏覽器訪問GitHub網(wǎng)站，你會發(fā)現(xiàn)此時網(wǎng)站上很多按鈕都不可用。。建議使用火狐或谷歌瀏覽器訪問GitHub
————————————————————————————
開始編輯README
打開你的GitHub的某個項目，我們可以直接在線編輯你的README文件，如果你已經(jīng)有了這個文件，則在文件目錄中直接點擊它，如果你還沒有這個文件那么點擊項目名稱右邊的一個按鈕，來添加新文件：
然后你就打開了編輯頁面，編輯區(qū)的左上角有填寫文件名的區(qū)域，注意加上后綴.md
如果你本來就有這個文件要重新編輯它的話，那么在點擊了文件目錄中的該文件后，在上方有工具欄，選擇Edit
然后滾動屏幕到下面，如果是新文件會有一個Commit new file的按鈕，若沒有內(nèi)容是不能點擊的。如果是舊文件重修編輯，那么這個按鈕顯示的是?Commit changes
//順便吐槽一句如果是360或搜狗瀏覽器的話，這個按鈕是永遠都無法點擊的，囧。。
先隨便寫的東西把這個新文件提交，然后再點擊 Edit 重新打開它。你會發(fā)現(xiàn)編輯區(qū)左上角有了變化。
默認選中Code，即我們的編輯模式。若點擊 Preview（預(yù)覽）就能實時顯示當前的顯示效果了。
好了，下面正式開始編輯這個文件
?
關(guān)于標題
規(guī)范的README文件開頭都寫上一個標題，這被稱為大標題。
?
[plain]?view plaincopy在文本下面加上 等于號 = ，那么上方的文本就變成了大標題。等于號的個數(shù)無限制，但一定要大于0個哦。。
?
比大標題低一級的是中標題，也就是顯示出來比大標題小點。
?
[plain]?view plaincopy在文本下面加上 下劃線 - ，那么上方的文本就變成了中標題，同樣的 下劃線個數(shù)無限制。
除此之外，你也會發(fā)現(xiàn)大，中標題下面都有一條橫線，沒錯這就是 = 和 - 的顯示結(jié)果。
如果你只輸入了等于號=，但其上方無文字，那么就只會顯示一條直線。如果上方有了文字，但你又只想顯示一條橫線，而不想把上方的文字轉(zhuǎn)義成大標題的話，那么你就要在等于號=和文字直接補一個空行。
補空行：是很常用的用法，當你不想上下兩個不同的布局方式交錯到一起的時候，就要在兩種布局之間補一個空行。
如果你只輸入了短橫線（減號）-，其上方無文字，那么要顯示直線，必須要寫三個減號以上。不過與等于號的顯示效果不同，它顯示出來時虛線而不是實線。同減號作用相同的還有星號*和下劃線_，同樣的這兩者符號也要寫三個以上才能顯示一條虛橫線。
?
除此以外，關(guān)于標題還有等級表示法，分為六個等級，顯示的文本大小依次減小。不同等級之間是以井號? #? 的個數(shù)來標識的。一級標題有一個 #，二級標題有兩個# ，以此類推。
?
[plain]?view plaincopy注意井號#和標題名稱要并排寫作一行，顯示效果如圖：
?
實際上，前文所述的大標題和中標題是分別和一級標題和二級標題對應(yīng)的。即大標題大小和一級標題相同，中標題大小和二級標題相同。
顯示文本
?
普通文本
直接輸入的文字就是普通文本。需要注意的是要換行的時候不能直接通過回車來換行，需要使用<br>(或者<br/>)。也就是html里面的標簽。事實上，markdown支持一些html標簽，你可以試試。當然如果你完全使用html來寫的話，就喪失意義了，畢竟markdown并非專門做前端的，然而僅實現(xiàn)一般效果的話，它會比html寫起來要簡潔得多得多啦。
?
[plain]?view plaincopy注意第三行的<br>前加了反斜杠 \ 。目的就是像其他語言那樣實現(xiàn)轉(zhuǎn)義，也就是 <? 的轉(zhuǎn)義。
?
效果如圖：
此外，要顯示一個超鏈接的話，就直接輸入這個鏈接的URL就好了。顯示出來會自動變成可鏈接的形式的。
顯示空格的小Tip
默認的文本行首空格都會被忽略的，但是如果你想用空格來排一下版的話怎么辦呢，有個小技巧，那就是把你的輸入法由半角改成全角就OK啦。單行文本
使用兩個Tab符實現(xiàn)單行文本。
?
[plain]?view plaincopy注意前面有兩個Tab。在GitHub上單行文本顯示效果如圖：
?
多行文本
多行文本和單行文本異曲同工，只要在每行行首加兩個Tab
?
[plain]?view plaincopy?
部分文字的高亮
如果你想使一段話中部分文字高亮顯示，來起到突出強調(diào)的作用，那么可以把它用 `? ` 包圍起來。注意這不是單引號，而是Tab上方，數(shù)字1左邊的按鍵（注意使用英文輸入法）。
Thank `You` . Please `Call` Me `Coder`
文字超鏈接
給一段文字加入超鏈接的格式是這樣的?[?要顯示的文字?](?鏈接的地址?)。比如：
?
[plain]?view plaincopy 顯示效果：
你還可以給他加上一個鼠標懸停顯示的文本。
?
[plain]?view plaincopy即在URL之后 用雙引號括起來一個字符串。同樣要注意這里是英文雙引號。
?
插入符號
圓點符
- 這是一個圓點符
- 這也是一個圓點符
上面這段的圓點是CSDN博客編輯器里面的符號列表。寫文章在列出條目時經(jīng)常用到。在GitHub的markdown語法里也支持使用圓點符。編輯的時候使用的是星號 *
?
[plain]?view plaincopy要注意的是星號* 后面要有一個空格。否則顯示為普通星號。上文的顯示效果如圖：
?
此外還有二級圓點和三級圓點。就是多加一個Tab。
?
[plain]?view plaincopy第二行一個Tab，第三行兩個Tab。這樣用來表示層級結(jié)構(gòu)就更清晰了吧，看效果：
?
如果你覺得三級的結(jié)構(gòu)還不夠表達清楚的話，我們可以試著換一種形式，請看字符包圍
?
縮進
縮進的含義是很容易理解的。。
?
[plain]?view plaincopy 顯示效果：
?
當然比這個更一般的用法是這樣。常常能在書籍里面看到的效果，比如引用別人的文章。直接看效果。
?
具體這個“縮進”的用法。大家自己摸索吧。
插入圖片
?
來源于網(wǎng)絡(luò)的圖片
?
網(wǎng)上有很多README插入圖片的教程了，經(jīng)我自己多次測試呢，發(fā)現(xiàn)可以使用的最簡單，最基本的語法是：
?
[plain]?view plaincopy即 嘆號! + 方括號[ ] + 括號( ) 其中嘆號里是圖片的URL。
如果不加嘆號! ,就會變成普通文本baidu了。
在方括號里可以加入一些 標識性的信息，比如
?
[plain]?view plaincopy?
這個方括號里的baidu并不會對圖像顯示造成任何改動，如果你想達到鼠標懸停顯示提示信息，那么可以仿照前面介紹的文本中的方法，就是這樣：
?
[plain]?view plaincopy在URL后面，加一個雙引號包圍的字符串，顯示效果如圖：
?
?
GitHub倉庫里的圖片
有時候我們想顯示一個GitHub倉庫(或者說項目)里的圖片而不是一張其他來源網(wǎng)絡(luò)圖片，因為其他來源的URL很可能會失效。那么如何顯示一個GitHub項目里的圖片呢？
其實與上面的格式基本一致的，所不同的就是括號里的URL該怎么寫。
??? https://github.com/?你的用戶名?/?你的項目名?/ raw /?分支名?/?存放圖片的文件夾?/?該文件夾下的圖片
這樣一目了然了吧。比如：
?
[plain]?view plaincopy我在GitHub上的用戶名guodongxiaren；有一個項目ImageCache；raw表示原數(shù)據(jù)的意思吧，不用管它；主分支master；項目里有一個文件夾Logo；Logo文件夾下有一張圖片foryou.gif
?
給圖片加上超鏈接
如果你想使圖片帶有超鏈接的功能，即點擊一個圖片進入一個指定的網(wǎng)頁。那么可以這樣寫：
?
[plain]?view plaincopy這兩句和前面的寫法差異較大，但是也極易模仿著寫出，就不過多介紹了。只需注意上下文中的 baidu 是你自己起的標識的名稱，可以隨意，但是一定要保證上下兩行的 標識 是一致的。
這樣就能實現(xiàn) 點擊圖片進入網(wǎng)頁的功能了。
?
插入代碼片段
我們需要在代碼的上一行和下一行用` `` 標記。``` 不是三個單引號，而是數(shù)字1左邊，Tab鍵上面的鍵。要實現(xiàn)語法高亮那么只要在 ``` 之后加上你的編程語言即可（忽略大小寫）。c++語言可以寫成c++也可以是cpp。看代碼：
實際顯示效果
[題外話]在GitHub上用Gist寫日記吧
看了這么多markdown的語法，你一定不滿足于僅僅寫一個README文件了，開始躍躍欲試想實際用markdown語法來編寫博客或文章了吧。的確，網(wǎng)上也有依托或者支持markdown語法的博客。但是呢，更方便的是，你可以借助GitHub本身就有的一個功能——Gist。
Gist是以文件為單位的，不是以項目為單位的。而且與普通的GitHub上建的倉庫不同，Gist是private的哦。普通的項目默認都是public的，要想弄成private貌似還要交錢的樣子。既然是private那么用來寫寫日記，是極好的。
GitHub網(wǎng)頁的頂部有：
點進去:
這就是你可以編輯的私有文件，它不僅支持Text文本，還支持各種編程語言呢！當然也包括markdown。輸入文件名：
最后保存，選中 Create Secret Gist 就是私有的嘍。
我在GitHub上為本文建的一個項目，供大家查看代碼即具體效果：https://github.com/guodongxiaren/test
轉(zhuǎn)載于:https://www.cnblogs.com/15ho/p/6596269.html
總結(jié)
以上是生活随笔為你收集整理的GitHub上README.md教程(copy)的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： FFT-Matlab初步实现
- 下一篇： 百度推出 MIP Baidu Path链