GitHub上README.md写法暨GFM语法解读

Posted 九茶

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了GitHub上README.md写法暨GFM语法解读相关的知识，希望对你有一定的参考价值。

转载请保留原作者guodongxiaren的原文地址：

http://blog.csdn.net/guodongxiaren/article/details/23690801

本文在GitHub的演示地址：

https://github.com/guodongxiaren/README

--------------------------------------------------------------------

自从开始玩GitHub以来，就越来越感觉它有爱。最近对它的README.md文件颇为感兴趣。便写下这贴，帮助更多的还不会编写README文件的同学们。

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

————————————————————————————

我在GitHub上为本文建的一个仓库“README”，供大家查看代码即具体效果：README 

本仓库README文件持续更新，新的知识点可能不会更新到博文中。首先强烈建议一条，不要用360或搜狗浏览器访问GitHub网站，你会发现此时网站上很多按钮都不可用。。建议使用火狐或谷歌浏览器访问GitHub

————————————————————————————

开始编辑README

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


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

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


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


//顺便吐槽一句如果是360或搜狗浏览器的话，这个按钮是永远都无法点击的，囧。。

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

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

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


关于标题

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

[plain]  view plain copy
  1. 大标题  
  2. ====  
在文本下面加上 等于号 = ，那么上方的文本就变成了大标题。等于号的个数无限制，但一定要大于0个哦。。

比大标题低一级的是中标题，也就是显示出来比大标题小点。

[plain]  view plain copy
  1. 中标题  
  2. -------  

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

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

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

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

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

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

[plain]  view plain copy
  1. #一级标题  
  2. ##二级标题  
  3. ###三级标题  
  4. ####四级标题  
  5. #####五级标题  
  6. ######六级标题  
注意井号#和标题名称要并排写作一行，显示效果如图：


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

显示文本


普通文本

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

[plain]  view plain copy
  1. 这是一段普通的文本，  
  2. 直接回车不能换行，<br>  
  3. 要使用\\<br>  
注意第三行的<br>前加了反斜杠 \\ 。目的就是像其他语言那样实现转义，也就是 <  的转义。

效果如图：

此外，要显示一个超链接的话，就直接输入这个链接的URL就好了。显示出来会自动变成可链接的形式的。

显示空格的小Tip

默认的文本行首空格都会被忽略的，但是如果你想用空格来排一下版的话怎么办呢，有个小技巧，那就是把你的输入法由半角改成全角就OK啦。

单行文本

使用两个Tab符实现单行文本。

[plain]  view plain copy
  1. Hello,大家好，我是果冻虾仁。  
注意前面有两个Tab。在GitHub上单行文本显示效果如图：


多行文本

多行文本和单行文本异曲同工，只要在每行行首加两个Tab

[plain]  view plain copy
  1. 欢迎到访  
  2. 很高兴见到您  
  3. 祝您，早上好，中午好，下午好，晚安  

部分文字的高亮

如果你想使一段话中部分文字高亮显示，来起到突出强调的作用，那么可以把它用 `  ` 包围起来。注意这不是单引号，而是Tab上方，数字1左边的按键（注意使用英文输入法）。

Thank `You` . Please `Call` Me `Coder`


文字超链接

给一段文字加入超链接的格式是这样的 [ 要显示的文字 ]( 链接的地址 )。比如：

[plain]  view plain copy
  1. [我的博客](http://blog.csdn.net/guodongxiaren)  
显示效果：

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

[plain]  view plain copy
  1. [我的博客](http://blog.csdn.net/guodongxiaren "悬停显示")  
即在URL之后 用双引号括起来一个字符串。同样要注意这里是英文双引号。


插入符号

圆点符

  • 这是一个圆点符
  • 这也是一个圆点符

上面这段的圆点是CSDN博客编辑器里面的符号列表。写文章在列出条目时经常用到。在GitHub的markdown语法里也支持使用圆点符。编辑的时候使用的是星号 *

[plain]  view plain copy
  1. * 昵称：果冻虾仁  
  2. * 别名：隔壁老王  
  3. * 英文名：Jelly  
要注意的是星号* 后面要有一个空格。否则显示为普通星号。上文的显示效果如图：


此外还有二级圆点和三级圆点。就是多加一个Tab。

[plain]  view plain copy
  1. * 编程语言  
  2.     * 脚本语言  
  3.         * Python  
第二行一个Tab，第三行两个Tab。这样用来表示层级结构就更清晰了吧，看效果：


如果你觉得三级的结构还不够表达清楚的话，我们可以试着换一种形式，请看字符包围


缩进

缩进的含义是很容易理解的。。

[plain]  github的README.md文件格式

GitHub ReadME.md

README.md文件 github Markdown语言详解 md文件用法和说明

github的README.md的markdown语法

github里的readme.md

MD文件