- 【原文】http://blog.csdn.net/guodongxiaren/article/details/23690801
本文解決了往github的readme檔案中換行、插圖、加url連結的問題,寫的相當詳細。
自從開始玩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檔案開頭都寫上一個标題,這被稱為大标題。
[plain] view plain copy
- 大标題
- ====
在文本下面加上 等于号 = ,那麼上方的文本就變成了大标題。等于号的個數無限制,但一定要大于0個哦。。
比大标題低一級的是中标題,也就是顯示出來比大标題小點。
[plain] view plain copy
- 中标題
- -------
在文本下面加上 下劃線 - ,那麼上方的文本就變成了中标題,同樣的 下劃線個數無限制。
除此之外,你也會發現大,中标題下面都有一條橫線,沒錯這就是 = 和 - 的顯示結果。
如果你隻輸入了等于号=,但其上方無文字,那麼就隻會顯示一條直線。如果上方有了文字,但你又隻想顯示一條橫線,而不想把上方的文字轉義成大标題的話,那麼你就要在等于号=和文字直接補一個空行。
補空行:是很常用的用法,當你不想上下兩個不同的布局方式交錯到一起的時候,就要在兩種布局之間補一個空行。
如果你隻輸入了短橫線(減号)-,其上方無文字,那麼要顯示直線,必須要寫三個減号以上。不過與等于号的顯示效果不同,它顯示出來時虛線而不是實線。同減号作用相同的還有星号*和下劃線_,同樣的這兩者符号也要寫三個以上才能顯示一條虛橫線。
除此以外,關于标題還有等級表示法,分為六個等級,顯示的文本大小依次減小。不同等級之間是以井号 # 的個數來辨別的。一級标題有一個 #,二級标題有兩個# ,以此類推。
[plain] view plain copy
- #一級标題
- ##二級标題
- ###三級标題
- ####四級标題
- #####五級标題
- ######六級标題
注意井号#和标題名稱要并排寫作一行,顯示效果如圖:
實際上,前文所述的大标題和中标題是分别和一級标題和二級标題對應的。即大标題大小和一級标題相同,中标題大小和二級标題相同。
顯示文本
普通文本
直接輸入的文字就是普通文本。需要注意的是要換行的時候不能直接通過回車來換行,需要使用<br>(或者<br/>)。也就是html裡面的标簽。事實上,markdown支援一些html标簽,你可以試試。當然如果你完全使用html來寫的話,就喪失意義了,畢竟markdown并非專門做前端的,然而僅實作一般效果的話,它會比html寫起來要簡潔得多得多啦。
[plain] view plain copy
- 這是一段普通的文本,
- 直接回車不能換行,<br>
- 要使用\<br>
注意第三行的<br>前加了反斜杠 \ 。目的就是像其他語言那樣實作轉義,也就是 < 的轉義。
效果如圖:
此外,要顯示一個超連結的話,就直接輸入這個連結的URL就好了。顯示出來會自動變成可連結的形式的。
顯示空格的小Tip
預設的文本行首空格都會被忽略的,但是如果你想用空格來排一下版的話怎麼辦呢,有個小技巧,那就是把你的輸入法由半角改成全角就OK啦。
單行文本
使用兩個Tab符實作單行文本。
[plain] view plain copy
- Hello,大家好,我是果凍蝦仁。
注意前面有兩個Tab。在GitHub上單行文本顯示效果如圖:
多行文本
多行文本和單行文本異曲同工,隻要在每行行首加兩個Tab
[plain] view plain copy
- 歡迎到訪
- 很高興見到您
- 祝您,早上好,中午好,下午好,晚安
部分文字的高亮
如果你想使一段話中部分文字高亮顯示,來起到突出強調的作用,那麼可以把它用 ` ` 包圍起來。注意這不是單引号,而是Tab上方,數字1左邊的按鍵(注意使用英文輸入法)。
Thank `You` . Please `Call` Me `Coder`
文字超連結
給一段文字加入超連結的格式是這樣的 [ 要顯示的文字 ]( 連結的位址 )。比如:
[plain] view plain copy
- [我的部落格](http://blog.csdn.net/guodongxiaren)
顯示效果:
你還可以給他加上一個滑鼠懸停顯示的文本。
[plain] view plain copy
- [我的部落格](http://blog.csdn.net/guodongxiaren "懸停顯示")
即在URL之後 用雙引号括起來一個字元串。同樣要注意這裡是英文雙引号。
插入符号
圓點符
- 這是一個圓點符
- 這也是一個圓點符
上面這段的圓點是CSDN部落格編輯器裡面的符号清單。寫文章在列出條目時經常用到。在GitHub的markdown文法裡也支援使用圓點符。編輯的時候使用的是星号 *
[plain] view plain copy
- * 昵稱:果凍蝦仁
- * 别名:隔壁老王
- * 英文名:Jelly
要注意的是星号* 後面要有一個空格。否則顯示為普通星号。上文的顯示效果如圖:
此外還有二級圓點和三級圓點。就是多加一個Tab。
[plain] view plain copy
- * 程式設計語言
- * 腳本語言
- * Python
第二行一個Tab,第三行兩個Tab。這樣用來表示層級結構就更清晰了吧,看效果:
如果你覺得三級的結構還不夠表達清楚的話,我們可以試着換一種形式,請看字元包圍
縮進
縮進的含義是很容易了解的。。
[plain] view plain copy
- >資料結構
- >>樹
- >>>二叉樹
- >>>>平衡二叉樹
- >>>>>滿二叉樹
顯示效果:
當然比這個更一般的用法是這樣。常常能在書籍裡面看到的效果,比如引用别人的文章。直接看效果。
具體這個“縮進”的用法。大家自己摸索吧。
插入圖檔
來源于網絡的圖檔
網上有很多README插入圖檔的教程了,經我自己多次測試呢,發現可以使用的最簡單,最基本的文法是:
[plain] view plain copy
- ![](http://www.baidu.com/img/bdlogo.gif)
即 歎号! + 方括号[ ] + 括号( ) 其中歎号裡是圖檔的URL。
如果不加歎号! ,就會變成普通文本baidu了。
在方括号裡可以加入一些 辨別性的資訊,比如
[plain] view plain copy
- ![baidu](http://www.baidu.com/img/bdlogo.gif)
這個方括号裡的baidu并不會對圖像顯示造成任何改動,如果你想達到滑鼠懸停顯示提示資訊,那麼可以仿照前面介紹的文本中的方法,就是這樣:
[plain] view plain copy
- ![baidu](http://www.baidu.com/img/bdlogo.gif "百度logo")
在URL後面,加一個雙引号包圍的字元串,顯示效果如圖:
GitHub倉庫裡的圖檔
有時候我們想顯示一個GitHub倉庫(或者說項目)裡的圖檔而不是一張其他來源網絡圖檔,因為其他來源的URL很可能會失效。那麼如何顯示一個GitHub項目裡的圖檔呢?
其實與上面的格式基本一緻的,所不同的就是括号裡的URL該怎麼寫。
https://github.com/ 你的使用者名 / 你的項目名 / raw / 分支名 / 存放圖檔的檔案夾 / 該檔案夾下的圖檔
這樣一目了然了吧。比如:
[plain] view plain copy
- ![](https://github.com/guodongxiaren/ImageCache/raw/master/Logo/foryou.gif)
我在GitHub上的使用者名guodongxiaren;有一個項目ImageCache;raw表示原資料的意思吧,不用管它;主分支master;項目裡有一個檔案夾Logo;Logo檔案夾下有一張圖檔foryou.gif
給圖檔加上超連結
如果你想使圖檔帶有超連結的功能,即點選一個圖檔進入一個指定的網頁。那麼可以這樣寫:
[plain] view plain copy
- [![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 就是私有的喽。
我在GitHub上為本文建的一個項目,供大家檢視代碼即具體效果:https://github.com/guodongxiaren/test