如何编写README.md？

最近对它的README.md文件颇为感兴趣。

帮助更多的还不会编写README文件的同学们。

README文件后缀名为md

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

开始编辑README

打开你的GitHub的某个项目，我们可以直接在线编辑你的README文件，如果你已经有了这个文件，则在文件目录中直接点击它，如果你还没有这个文件那么点击项目名称右边的一个按钮，来添加新文件：

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

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

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

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

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

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

大标题

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

[plain] view plaincopy在CODE上查看代码片派生到我的代码片

大标题

在文本下面加上 等于号 = ，那么上方的文本就变成了大标题。等于号的个数无限制，但一定要大于0个哦。。
比大标题低一级的是中标题，也就是显示出来比大标题小点。

[plain] view plaincopy在CODE上查看代码片派生到我的代码片

中标题

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

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

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

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

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

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

[plain] view plaincopy在CODE上查看代码片派生到我的代码片

#一级标题

##二级标题

###三级标题

####四级标题

#####五级标题

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

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

显示文本

普通文本
直接输入的文字就是普通文本。需要注意的是要换行的时候不能直接通过回车来换行，需要使用
(或者
)。也就是html里面的标签。事实上，markdown支持一些html标签，你可以试试。当然如果你完全使用html来写的话，就丧失意义了，毕竟markdown并非专门做前端的，然而仅实现一般效果的话，它会比html写起来要简洁得多得多啦。

[plain] view plaincopy在CODE上查看代码片派生到我的代码片

这是一段普通的文本，
直接回车不能换行，

要使用\

注意第三行的
前加了反斜杠 \ 。目的就是像其他语言那样实现转义，也就是 < 的转义。
效果如图：

此外，要显示一个超链接的话，就直接输入这个链接的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上查看代码片派生到我的代码片

我的博客
显示效果：

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

[plain] view plaincopy在CODE上查看代码片派生到我的代码片

我的博客
即在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
这个方括号里的baidu并不会对图像显示造成任何改动，如果你想达到鼠标悬停显示提示信息，那么可以仿照前面介绍的文本中的方法，就是这样：

[plain] view plaincopy在CODE上查看代码片派生到我的代码片

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

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

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

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

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

[plain] view plaincopy在CODE上查看代码片派生到我的代码片

给图片加上超链接
如果你想使图片带有超链接的功能，即点击一个图片进入一个指定的网页。那么可以这样写：

[plain] view plaincopy在CODE上查看代码片派生到我的代码片

![baidu]
[baidu]:http://www.baidu.com/img/bdlogo.gif “百度Logo”
这两句和前面的写法差异较大，但是也极易模仿着写出，就不过多介绍了。只需注意上下文中的 baidu 是你自己起的标识的名称，可以随意，但是一定要保证上下两行的 标识 是一致的。
这样就能实现 点击图片进入网页的功能了。

插入代码片段
我们需要在代码的上一行和下一行用` 标记。

``` 之后加上你的编程语言即可（忽略大小写）。c++语言可以写成c++也可以是cpp。看代码：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112



实际显示效果



[题外话]在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】找到我

1
2
3
4
该语法也可以实现代码高亮，见[代码高亮](#代码高亮)
### 文字高亮
文字高亮功能能使行内部分文字高亮，使用一对反引号。
语法：

linux 网络编程 socket epoll

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
效果：`linux` `网络编程` `socket` `epoll`

也适合做一篇文章的tag
#### 换行
直接回车不能换行，  
可以在上一行文本后面补两个空格，  
这样下一行的文本就换行了。

或者就是在两行文本直接加一个空行。

也能实现换行效果，不过这个行间距有点大。
#### 斜体、粗体、删除线

|语法|效果|
|----|-----|
|`*斜体1*`|*斜体1*|
|`_斜体2_`| _斜体2_|
|`**粗体1**`|**粗体1**|
|`__粗体2__`|__粗体2__|
|`这是一个 ~~删除线~~`|这是一个 ~~删除线~~|
|`***斜粗体1***`|***斜粗体1***|
|`___斜粗体2___`|___斜粗体2___|
|`***~~斜粗体删除线1~~***`|***~~斜粗体删除线1~~***|
|`~~***斜粗体删除线2***~~`|~~***斜粗体删除线2***~~|

    斜体、粗体、删除线可混合使用

图片
====
基本格式：

alt

1
2
3
4
5
alt和title即对应HTML中的alt和title属性（都可省略）：
- alt表示图片显示失败时的替换文本
- title表示鼠标悬停在图片时的显示文本（注意这里要加引号）

URL即图片的url地址，如果引用本仓库中的图片，直接使用**相对路径**就可了，如果引用其他github仓库中的图片要注意格式，即：`仓库地址/raw/分支名/图片路径`，如：

https://github.com/xxx/ImageCache/raw/master/Logo/foryou.gif

1
2
3
4
5
6
7
8

|#|语法|效果|
|---|---|----
|1|`![baidu](http://www.baidu.com/img/bdlogo.gif "百度logo")`|![baidu](http://www.baidu.com/img/bdlogo.gif "百度logo")
|2|`![][foryou]`|![][foryou]

注意例2的写法使用了**URL标识符**的形式，在[链接](#链接)一节有介绍。
>在文末有foryou的定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

链接
====
### 链接外部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|`[![weibo-logo]](http://weibo.com)`|[![weibo-logo]](http://weibo.com/)|
|2|`[![](/img/zhihu.png "我的知乎，欢迎关注")][zhihu]`|[![](/img/zhihu.png "我的知乎，欢迎关注")][zhihu]|
|3|`[![csdn-logo]][csdn]`|[![csdn-logo]][csdn]|

因为图片本身和链接本身都支持URL标识符的形式，所以图片链接也可以很简洁（见例3）。  
注意，此时鼠标悬停时显示的文字是图片的title，而非链接本身的title了。
> 本文URL标识符都放置于文末

### 锚点
其实呢，每一个标题都是一个锚点，和HTML的锚点（`#`）类似，比如我们 

|语法|效果|
|---|---|
|`[回到顶部](#readme)`|[回到顶部](#readme)|

不过要注意，标题中的英文字母都被转化为**小写字母**了。
> 以前GitHub对中文支持的不好，所以中文标题不能正确识别为锚点，但是现在已经没问题啦！

## 列表
### 无序列表
#### 语法
  • 昵称：liyinchi
  • 别名：方块银

  • 英文名：Jack Li

    1
    2
    3
    4
    5
    6
    7
    #### 效果
    * 昵称：liyinchi
    - 别名：方块银
    * 英文名：Jack Li

    ### 多级无序列表
    #### 语法

  • 编程语言

    • 脚本语言
      • JAVA
        1
        2
        3
        4
        5
        6
        7
        8
        #### 效果
        * 编程语言
            * 脚本语言
                * JAVA

        ### 一级有序列表
        #### 语法
        就是在数字后面加一个点，再加一个空格。不过看起来起来可能不够明显。

面向对象的三个基本特征：

  1. 封装
  2. 继承

  3. 多态

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12

    #### 效果
    面向对象的三个基本特征：

    1. 封装
    2. 继承
    3. 多态


    ### 多级有序列表
    和无序列表一样，有序列表也有多级结构。
    #### 语法

  4. 这是一级的有序列表，数字1还是1

    1. 这是二级的有序列表，阿拉伯数字在显示的时候变成了罗马数字
      1. 这是三级的有序列表，数字在显示的时候变成了英文字母
        1
        2
        3
        4
        5
        6
        7
        8
        9
        10

        #### 效果

        1. 这是一级的有序列表，数字1还是1
           1. 这是二级的有序列表，阿拉伯数字在显示的时候变成了罗马数字
              1. 这是三级的有序列表，数字在显示的时候变成了英文字母
        	 

        ### 复选框列表
        #### 语法
  • 需求分析
  • 系统设计
  • 详细设计
  • 编码
  • 测试
  • 交付
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    #### 效果

    - [x] 需求分析
    - [x] 系统设计
    - [x] 详细设计
    - [ ] 编码
    - [ ] 测试
    - [ ] 交付

    您可以使用这个功能来标注某个项目各项任务的完成情况。
    > Tip:
    >> 在GitHub的**issue**中使用该语法是可以实时点击复选框来勾选或解除勾选的，而无需修改issue原文。

    ## 块引用

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

    ### 块引用有多级结构
    #### 语法

数据结构

树

二叉树

平衡二叉树

满二叉树

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#### 效果
> 数据结构
>> 树
>>> 二叉树
>>>> 平衡二叉树
>>>>> 满二叉树

代码高亮
====

### 语法
在三个反引号后面加上编程语言的名字，另起一行开始写代码，最后一行再加上三个反引号。

### 效果

public static void main(String[]args){} //Java

1
2
```c
int main(int argc, char *argv[]) //C

1
echo "hello GitHub" #Bash
1
document.getElementById("myH1").innerHTML="Welcome to my Homepage"; //javascipt
1
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。

但是这个网页每次都打开奇慢。。所以我整理到了本repo中，大家可以直接在此查看emoji。

diff语法

版本控制的系统中都少不了diff的功能，即展示一个文件内容的增加与删除。
GFM中可以显示的展示diff效果。使用绿色表示新增，红色表示删除。

语法

其语法与代码高亮类似，只是在三个反引号后面写diff，
并且其内容中，以 +开头表示新增，-开头表示删除。

效果

1
2
+ 鸟宿池边树，僧敲月下门
- 鸟宿池边树，僧推月下门

声明

转载请注明出处：https://liyinchigithub.github.io/ 谢谢您的配合