README文件编写
一直對README.md文件頗為感興趣,每個工程根目錄都要放置。
md是markdown的縮寫,markdown是一種編輯博客的語言。用慣了可視化的博客編輯器(比如CSDN博客,囧),這種編程式的博客編輯方案著實讓人眼前一亮。不過GitHub支持的語法在標準markdown語法的基礎上做了修改,稱為Github Flavored Markdown,簡稱GFM。
大標題 ?
====?
規范的README文件開頭都寫上一個標題,這被稱為大標題。
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
大標題 ?
==== ?
在文本下面加上 等于號 = ,那么上方的文本就變成了大標題。等于號的個數無限制,但一定要大于0個哦。。
比大標題低一級的是中標題,也就是顯示出來比大標題小點。
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
中標題 ?
====
在文本下面加上 下劃線 - ,那么上方的文本就變成了中標題,同樣的 下劃線個數無限制。
除此之外,你也會發現大,中標題下面都有一條橫線,沒錯這就是 = 和 - 的顯示結果。
如果你只輸入了等于號=,但其上方無文字,那么就只會顯示一條直線。如果上方有了文字,但你又只想顯示一條橫線,而不想把上方的文字轉義成大標題的話,那么你就要在等于號=和文字直接補一個空行。
補空行:是很常用的用法,當你不想上下兩個不同的布局方式交錯到一起的時候,就要在兩種布局之間補一個空行。
如果你只輸入了短橫線(減號)-,其上方無文字,那么要顯示直線,必須要寫三個減號以上。不過與等于號的顯示效果不同,它顯示出來時虛線而不是實線。同減號作用相同的還有星號*和下劃線_,同樣的這兩者符號也要寫三個以上才能顯示一條虛橫線。
除此以外,關于標題還有等級表示法,分為六個等級,顯示的文本大小依次減小。不同等級之間是以井號 ?# ?的個數來標識的。一級標題有一個 #,二級標題有兩個# ,以此類推。
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
#一級標題 ?
##二級標題 ?
###三級標題 ?
####四級標題 ?
#####五級標題 ?
######六級標題 ?
注意井號#和標題名稱要并排寫作一行,顯示效果如圖:
實際上,前文所述的大標題和中標題是分別和一級標題和二級標題對應的。即大標題大小和一級標題相同,中標題大小和二級標題相同。
顯示文本 ?
====
普通文本
直接輸入的文字就是普通文本。需要注意的是要換行的時候不能直接通過回車來換行,需要使用<br>(或者<br/>)。也就是html里面的標簽。事實上,markdown支持一些html標簽,你可以試試。當然如果你完全使用html來寫的話,就喪失意義了,畢竟markdown并非專門做前端的,然而僅實現一般效果的話,它會比html寫起來要簡潔得多得多啦。
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
這是一段普通的文本, ?
直接回車不能換行,<br> ?
要使用\<br> ?
注意第三行的<br>前加了反斜杠 \ 。目的就是像其他語言那樣實現轉義,也就是 < ?的轉義。
效果如圖:
此外,要顯示一個超鏈接的話,就直接輸入這個鏈接的URL就好了。顯示出來會自動變成可鏈接的形式的。
顯示空格的小Tip
默認的文本行首空格都會被忽略的,但是如果你想用空格來排一下版的話怎么辦呢,有個小技巧,那就是把你的輸入法由半角改成全角就OK啦。
單行文本
使用兩個Tab符實現單行文本。
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
Hello,大家好,我是方塊銀。 ?
注意前面有兩個Tab。在GitHub上單行文本顯示效果如圖:
多行文本
多行文本和單行文本異曲同工,只要在每行行首加兩個Tab
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
歡迎到訪 ?
很高興見到您 ?
祝您,早上好,中午好,下午好,晚安 ?
部分文字的高亮
如果你想使一段話中部分文字高亮顯示,來起到突出強調的作用,那么可以把它用 ` ?` 包圍起來。注意這不是單引號,而是Tab上方,數字1左邊的按鍵(注意使用英文輸入法)。
Thank `You` . Please `Call` Me `Coder`
文字超鏈接
====
給一段文字加入超鏈接的格式是這樣的 [ 要顯示的文字 ]( 鏈接的地址 )。比如:
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
[我的博客](https://liyinchigithub.github.io) ?
顯示效果:
你還可以給他加上一個鼠標懸停顯示的文本。
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
[我的博客](https://liyinchigithub.github.io "懸停顯示") ?
即在URL之后 用雙引號括起來一個字符串。同樣要注意這里是英文雙引號。
插入符號
圓點符
這是一個圓點符
這也是一個圓點符
上面這段的圓點是CSDN博客編輯器里面的符號列表。寫文章在列出條目時經常用到。在GitHub的markdown語法里也支持使用圓點符。編輯的時候使用的是星號 *
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
* 昵稱:liyinchi?
* 別名:方塊銀
* 英文名:Jack li ?
要注意的是星號* 后面要有一個空格。否則顯示為普通星號。上文的顯示效果如圖:
此外還有二級圓點和三級圓點。就是多加一個Tab。
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
* 編程語言 ?
? ? * 腳本語言 ?
? ? ? ? * Python ?
第二行一個Tab,第三行兩個Tab。這樣用來表示層級結構就更清晰了吧,看效果:
如果你覺得三級的結構還不夠表達清楚的話,我們可以試著換一種形式,請看字符包圍
縮進
縮進的含義是很容易理解的。。
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
>數據結構 ?
>>樹 ?
>>>二叉樹 ?
>>>>平衡二叉樹 ?
>>>>>滿二叉樹 ?
顯示效果:
當然比這個更一般的用法是這樣。常常能在書籍里面看到的效果,比如引用別人的文章。直接看效果。
具體這個“縮進”的用法。大家自己摸索吧。
插入圖片
來源于網絡的圖片
網上有很多README插入圖片的教程了,經我自己多次測試呢,發現可以使用的最簡單,最基本的語法是:
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
 ?
即 嘆號! + 方括號[ ] + 括號( ) 其中嘆號里是圖片的URL。
如果不加嘆號! ,就會變成普通文本baidu了。
在方括號里可以加入一些 標識性的信息,比如
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
 ?
這個方括號里的baidu并不會對圖像顯示造成任何改動,如果你想達到鼠標懸停顯示提示信息,那么可以仿照前面介紹的文本中的方法,就是這樣:
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳(img-XRcW9ciu-1618134352507)(http://www.baidu.com/img/bdlogo.gif "百度logo")] ?
在URL后面,加一個雙引號包圍的字符串,顯示效果如圖:
GitHub倉庫里的圖片
有時候我們想顯示一個GitHub倉庫(或者說項目)里的圖片而不是一張其他來源網絡圖片,因為其他來源的URL很可能會失效。那么如何顯示一個GitHub項目里的圖片呢?
其實與上面的格式基本一致的,所不同的就是括號里的URL該怎么寫。
? ? https://github.com/ 你的用戶名 / 你的項目名 / raw / 分支名 / 存放圖片的文件夾 / 該文件夾下的圖片
這樣一目了然了吧。比如:
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
![]() ?
給圖片加上超鏈接
如果你想使圖片帶有超鏈接的功能,即點擊一個圖片進入一個指定的網頁。那么可以這樣寫:
[plain] view plaincopy在CODE上查看代碼片派生到我的代碼片
[[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳(img-xcDao8UM-1618134352509)(http://baidu.com)] ?
[baidu]:http://www.baidu.com/img/bdlogo.gif "百度Logo" ?
這兩句和前面的寫法差異較大,但是也極易模仿著寫出,就不過多介紹了。只需注意上下文中的 baidu 是你自己起的標識的名稱,可以隨意,但是一定要保證上下兩行的 標識 是一致的。
這樣就能實現 點擊圖片進入網頁的功能了。
插入代碼片段
我們需要在代碼的上一行和下一行用` `` 標記。```不是三個單引號,而是數字1左邊,Tab鍵上面的鍵。要實現語法高亮那么只要在 ```之后加上你的編程語言即可(忽略大小寫)。c++語言可以寫成c++也可以是cpp??创a:
實際顯示效果
[題外話]在GitHub上用Gist寫日記吧
看了這么多markdown的語法,你一定不滿足于僅僅寫一個README文件了,開始躍躍欲試想實際用markdown語法來編寫博客或文章了吧。的確,網上也有依托或者支持markdown語法的博客。但是呢,更方便的是,你可以借助GitHub本身就有的一個功能——Gist。
Gist是以文件為單位的,不是以項目為單位的。而且與普通的GitHub上建的倉庫不同,Gist是private的哦。普通的項目默認都是public的,要想弄成private貌似還要交錢的樣子。既然是private那么用來寫寫日記,是極好的。
GitHub網頁的頂部有:
點進去:
這就是你可以編輯的私有文件,它不僅支持Text文本,還支持各種編程語言呢!當然也包括markdown。輸入文件名:
最后保存,選中 Create Secret Gist 就是私有的嘍。
-----------下面是一個README.md例子
README
====
該文件用來測試和展示書寫README的各種markdown語法。GitHub的markdown語法在標準的markdown語法基礎上做了擴充,稱之為`GitHub Flavored Markdown`。簡稱`GFM`,GFM在GitHub上有廣泛應用,除了README文件外,issues和wiki均支持markdown語法。
****
?? ?
|Author|JackLi|
|---|---
|E-mail|liyinchi@qq.com
****
## 目錄
* [橫線](#橫線)
* [標題](#標題)
* [文本](#文本)
? ? * 普通文本
? ? * 單行文本
? ? * 多行文本
? ? * 文字高亮
? ? * 換行
? ? * 斜體
? ? * 粗體
? ? * 刪除線
* [圖片](#圖片)
? ? * 來源于網絡的圖片
? ? * GitHub倉庫中的圖片
* [鏈接](#鏈接)?
? ? * 文字超鏈接
? ? ? ? * ?鏈接外部URL
? ? ? ? * ?鏈接本倉庫里的URL
? ? * ?錨點
? ? * [圖片鏈接](#圖片鏈接)
* [列表](#列表)
? ? * 無序列表
? ? * 有序列表
? ? * 復選框列表
* [塊引用](#塊引用)
* [代碼高亮](#代碼高亮)
* [表格](#表格)?
* [表情](#表情)
* [diff語法](#diff語法)
### 橫線
-----------
***、---、___可以顯示橫線效果
***
---
___
標題
====
# 一級標題 ?
## 二級標題 ?
### 三級標題 ?
#### 四級標題 ?
##### 五級標題 ?
###### 六級標題 ?
文本
====
### 普通文本
這是一段普通的文本
### 單行文本
? ? Hello,大家好,我是Jack li。
在一行開頭加入1個Tab或者4個空格。
### 文本塊
#### 語法1
在連續幾行的文本開頭加入1個Tab或者4個空格。
? ? 歡迎到訪
? ? 很高興見到您
? ? 祝您,早上好,中午好,下午好,晚安
#### 語法2
使用一對各三個的反引號:
```
歡迎到訪
我是JavaScript、Java碼農
你可以在github搜索【liyinchi】找到我
```
該語法也可以實現代碼高亮,見[代碼高亮](#代碼高亮)
### 文字高亮
文字高亮功能能使行內部分文字高亮,使用一對反引號。
語法:
```
`linux` `網絡編程` `socket` `epoll`?
```
效果:`linux` `網絡編程` `socket` `epoll`
也適合做一篇文章的tag
#### 換行
直接回車不能換行, ?
可以在上一行文本后面補兩個空格, ?
這樣下一行的文本就換行了。
或者就是在兩行文本直接加一個空行。
也能實現換行效果,不過這個行間距有點大。
#### 斜體、粗體、刪除線
|語法|效果|
|----|-----|
|`*斜體1*`|*斜體1*|
|`_斜體2_`| _斜體2_|
|`**粗體1**`|**粗體1**|
|`__粗體2__`|__粗體2__|
|`這是一個 ~~刪除線~~`|這是一個 ~~刪除線~~|
|`***斜粗體1***`|***斜粗體1***|
|`___斜粗體2___`|___斜粗體2___|
|`***~~斜粗體刪除線1~~***`|***~~斜粗體刪除線1~~***|
|`~~***斜粗體刪除線2***~~`|~~***斜粗體刪除線2***~~|
? ? 斜體、粗體、刪除線可混合使用
圖片
====
基本格式:
```

```
alt和title即對應HTML中的alt和title屬性(都可省略):
- alt表示圖片顯示失敗時的替換文本
- title表示鼠標懸停在圖片時的顯示文本(注意這里要加引號)
URL即圖片的url地址,如果引用本倉庫中的圖片,直接使用**相對路徑**就可了,如果引用其他github倉庫中的圖片要注意格式,即:`倉庫地址/raw/分支名/圖片路徑`,如:
```
https://github.com/xxx/ImageCache/raw/master/Logo/foryou.gif
```
|#|語法|效果|
|---|---|----
|1|`[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳(img-f5FYUsu7-1618134352512)(http://www.baidu.com/img/bdlogo.gif "百度logo")]`|[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳(img-ipealoFp-1618134352513)(http://www.baidu.com/img/bdlogo.gif "百度logo")]
|2|`![][foryou]`|![][foryou]
注意例2的寫法使用了**URL標識符**的形式,在[鏈接](#鏈接)一節有介紹。
>在文末有foryou的定義:
```
[foryou]:https://github.com/
```
鏈接
====
### 鏈接外部URL
|#|語法|效果|
|---|----|-----|
|1|`[我的博客](https://liyinchigithub.github.io/ "懸停顯示")`|[我的博客](https://liyinchigithub.github.io/ "懸停顯示")|
語法2由兩部分組成:
- 第一部分使用兩個中括號,[ ]里的標識符(本例中zhihu),可以是數字,字母等的組合,標識符上下對應就行了(**姑且稱之為URL標識符**)
- 第二部分標記實際URL。
>使用URL標識符能達到復用的目的,一般把全文所有的URL標識符統一放在文章末尾,這樣看起來比較干凈。
>>URL標識符是我起的名字,不知道是否準確。囧。。
### 鏈接本倉庫里的URL
|語法|效果|
|----|-----|
|`[我的簡介](/example/profile.md)`|[我的簡介](/example/profile.md)|
|`[example](./example)`|[example](./example)|
### 圖片鏈接
給圖片加鏈接的本質是混合圖片顯示語法和普通的鏈接語法。普通的鏈接中[ ]內部是鏈接要顯示的文本,而圖片鏈接[ ]里面則是要顯示的圖片。 ?
直接混合兩種語法當然可以,但是十分啰嗦,為此我們可以使用URL標識符的形式。
|#|語法|效果|
|---|----|:---:|
|1|`[[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳(img-MMn9Lkdu-1618134352514)(http://weibo.com)]`|[[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳(img-qf86YEax-1618134352515)(http://weibo.com/)]|
|2|`[[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳(img-2qJxQENK-1618134352515)(/img/zhihu.png "我的知乎,歡迎關注")]][zhihu]`|[[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳(img-gvmexJWa-1618134352516)(/img/zhihu.png "我的知乎,歡迎關注")]][zhihu]|
|3|`[![csdn-logo]][csdn]`|[![csdn-logo]][csdn]|
因為圖片本身和鏈接本身都支持URL標識符的形式,所以圖片鏈接也可以很簡潔(見例3)。 ?
注意,此時鼠標懸停時顯示的文字是圖片的title,而非鏈接本身的title了。
> 本文URL標識符都放置于文末
### 錨點
其實呢,每一個標題都是一個錨點,和HTML的錨點(`#`)類似,比如我們?
|語法|效果|
|---|---|
|`[回到頂部](#readme)`|[回到頂部](#readme)|
不過要注意,標題中的英文字母都被轉化為**小寫字母**了。
> 以前GitHub對中文支持的不好,所以中文標題不能正確識別為錨點,但是現在已經沒問題啦!
## 列表
### 無序列表
#### 語法
```
* 昵稱:liyinchi
- 別名:方塊銀
* 英文名:Jack Li
```
#### 效果
* 昵稱:liyinchi
- 別名:方塊銀
* 英文名:Jack Li
### 多級無序列表
#### 語法
```
* 編程語言
? ? * 腳本語言
? ? ? ? * JAVA
```
#### 效果
* 編程語言
? ? * 腳本語言
? ? ? ? * JAVA
### 一級有序列表
#### 語法
就是在數字后面加一個點,再加一個空格。不過看起來起來可能不夠明顯。?
```
面向對象的三個基本特征:
1. 封裝
2. 繼承
3. 多態
```
#### 效果
面向對象的三個基本特征:
1. 封裝
2. 繼承
3. 多態
### 多級有序列表
和無序列表一樣,有序列表也有多級結構。
#### 語法
```
1. 這是一級的有序列表,數字1還是1
? ?1. 這是二級的有序列表,阿拉伯數字在顯示的時候變成了羅馬數字
? ? ? 1. 這是三級的有序列表,數字在顯示的時候變成了英文字母
```
#### 效果
1. 這是一級的有序列表,數字1還是1
? ?1. 這是二級的有序列表,阿拉伯數字在顯示的時候變成了羅馬數字
? ? ? 1. 這是三級的有序列表,數字在顯示的時候變成了英文字母
?? ??
### 復選框列表
#### 語法
```
- [x] 需求分析
- [x] 系統設計
- [x] 詳細設計
- [ ] 編碼
- [ ] 測試
- [ ] 交付
```
#### 效果
- [x] 需求分析
- [x] 系統設計
- [x] 詳細設計
- [ ] 編碼
- [ ] 測試
- [ ] 交付
您可以使用這個功能來標注某個項目各項任務的完成情況。
> Tip:
>> 在GitHub的**issue**中使用該語法是可以實時點擊復選框來勾選或解除勾選的,而無需修改issue原文。
## 塊引用
### 常用于引用文本
#### 文本摘自《深入理解計算機系統》P27
令人吃驚的是,在哪種字節順序是合適的這個問題上,人們表現得非常情緒化。實際上術語“little endian”(小端)和“big endian”(大端)出自Jonathan Swift的《格利佛游記》一書,其中交戰的兩個派別無法就應該從哪一端打開一個半熟的雞蛋達成一致。因此,爭論淪為關于社會政治的爭論。只要選擇了一種規則并且始終如一的堅持,其實對于哪種字節排序的選擇都是任意的。
> **“端”(endian)的起源** ?
以下是Jonathan Swift在1726年關于大小端之爭歷史的描述: ?
“……下面我要告訴你的是,Lilliput和Blefuscu這兩大強國在過去36個月里一直在苦戰。戰爭開始是由于以下的原因:我們大家都認為,吃雞蛋前,原始的方法是打破雞蛋較大的一端,可是當今的皇帝的祖父小時候吃雞蛋,一次按古法打雞蛋時碰巧將一個手指弄破了,因此他的父親,當時的皇帝,就下了一道敕令,命令全體臣民吃雞蛋時打破較小的一端,違令者重罰。”
### 塊引用有多級結構
#### 語法
```
> 數據結構
>> 樹
>>> 二叉樹
>>>> 平衡二叉樹
>>>>> 滿二叉樹
```
#### 效果
> 數據結構
>> 樹
>>> 二叉樹
>>>> 平衡二叉樹
>>>>> 滿二叉樹
代碼高亮
====
### 語法
在三個反引號后面加上編程語言的名字,另起一行開始寫代碼,最后一行再加上三個反引號。
### 效果
```
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
```
表格
====
表頭1 ?| 表頭2|
--------- | --------|
表格單元 ?| 表格單元 |
表格單元 ?| 表格單元 |
| 表頭1 ?| 表頭2|
| ---------- | -----------|
| 表格單元 ? | 表格單元 ? |
| 表格單元 ? | 表格單元 ? |
### 對齊
表格可以指定對齊方式
| 左對齊 | 居中 ?| 右對齊 |
| :------------ |:---------------:| -----:|
| col 3 is ? ? ?| some wordy text | $1600 |
| col 2 is ? ? ?| centered ? ? ? ?| ? $12 |
| zebra stripes | are neat ? ? ? ?| ? ?$1 |
### 混合其他語法
表格單元中的內容可以和其他大多數GFM語法配合使用,如: ?
#### 使用普通文本的刪除線,斜體等效果
| 名字 | 描述 |
| ------------- | ----------- |
| Help ? ? ?| ~~Display the~~ help window.|
| Close ? ? | _Closes_ a window ? ? |
#### 表格中嵌入圖片(鏈接)
其實前面介紹圖片顯示、圖片鏈接的時候為了清晰就是放在在表格中顯示的。
| 圖片 | 描述 |
| ---- | ---- |
|![baidu][baidu-logo] | 百度|
表情
----------
Github的Markdown語法支持添加emoji表情,輸入不同的符號碼(兩個冒號包圍的字符)可以顯示出不同的表情。
比如`:blush:`,可以顯示:blush:。
具體每一個表情的符號碼,可以查詢GitHub的官方網頁[http://www.emoji-cheat-sheet.com](http://www.emoji-cheat-sheet.com)。
但是這個網頁每次都打開**奇慢**。。所以我整理到了本repo中,大家可以直接在此查看[emoji](./emoji.md)。
diff語法
---------
版本控制的系統中都少不了diff的功能,即展示一個文件內容的增加與刪除。
GFM中可以顯示的展示diff效果。使用綠色表示新增,紅色表示刪除。
#### 語法
其語法與代碼高亮類似,只是在三個反引號后面寫diff,
并且其內容中,以 `+ `開頭表示新增,`- `開頭表示刪除。
#### 效果
```diff
+ 鳥宿池邊樹,僧敲月下門
- 鳥宿池邊樹,僧推月下門
```
聲明
===
轉載請注明出處:https://liyinchigithub.github.io/ ?謝謝您的配合
總結
以上是生活随笔為你收集整理的README文件编写的全部內容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: Linux下屏保程序
- 下一篇: 主流的Bootstrap 在线编辑器