markdown github markdown语法 markdown引擎 学习markdown

文档说明

---

本文用来测试和展示书写README的各种markdown语法。

详细高阶教程请等待后续说明

GitHub的markdown语法在标准的markdown语法基础上做了扩充，称之为GitHub Flavored Markdown。简称GFM，GFM在GitHub上有广泛应用，除了README文件外，issues和wiki均支持markdown语法。

注意：

不同的markdown引擎均有可能做了不同的渲染处理，本文仅以github常用的markdown来做举例说明，

---

横线

示例：

--------------------
============
******************

---

============

---

由于不同引擎渲染效果不同，建议只使用 ---------- 来表示横线，因为实测 --------- 是最通用的语法

---

标题

一级标题

二级标题

三级标题

四级标题

五级标题

六级标题

# 一级标题  
## 二级标题  
### 三级标题  
#### 四级标题  
##### 五级标题  
###### 六级标题

居中标题(简书语法不支持）

由于markdown 定义全支持html标记，所以你可以直接在markdown里面写html语法。

<center>居中渲染</center>

居中渲染效果

---

文本

注意，关于换行，文字默认定义为段落，也就是说你如果想要段落换行的话，需要输入换行，否则你的文本是默认为一个段落，是否换行取决于渲染引擎以及显示宽度。

下面以一段markdown作者的简介作为示例：

---

毫无疑问，Aaron Swartz 是个天才。 创造 RSS 1.0 规则，开发 Web.py，参与 W3C 组织，创立 Infogami（后与 Reddit 合并），创立 Open Library，参与设计 Markdown 排版语言。程序员，作家，互联网活动家。 在 26 岁，他的成就足以使我们许多人掩面羞愧。 毫无疑问，Aaron Swartz 是个好人。 他的好朋友 Lawrence Lessig 说，“在他的一生中，Aaron 从未做过任何 ‘为赚钱’ 的事情……Aaron 只为公益而工作，一贯如此（至少他是这样想的）。他聪明，有趣。一个天才儿童。一个灵魂、一个良心、一个问题的源头，他曾经让我百万次问自己：Aaron 会这样想？” 曾和他一起开发了 MarkDown 的 John Gruber 说，“Aaron 有着非常出众的才智 ——再说一次，非常聪明的头脑——但同时也有一颗巨大的宽容心。他是一个了不起的人”。

你可以添加HTML标记<br>在需要手动换行的位置，也可以直接输入换行符切换到下一行要留意你的编辑器是否允许你在编辑段落的时候输入换行符。

毫无疑问，Aaron Swartz 是个天才。 创造 RSS 1.0 规则，开发 Web.py，参与 W3C 组织，创立 Infogami（后与 Reddit 合并），创立 Open Library，参与设计 Markdown 排版语言。程序员，作家，互联网活动家。 <br>在 26 岁，他的成就足以使我们许多人掩面羞愧。 毫无疑问，Aaron Swartz 是个好人。 他的好朋友 Lawrence Lessig 说，“在他的一生中，Aaron 从未做过任何 ‘为赚钱’ 的事情……Aaron 只为公益而工作，一贯如此（至少他是这样想的）。他聪明，有趣。一个天才儿童。一个灵魂、一个良心、一个问题的源头，他曾经让我百万次问自己：Aaron 会这样想？” 
曾和他一起开发了 MarkDown 的 John Gruber 说，“Aaron 有着非常出众的才智 ——再说一次，非常聪明的头脑——但同时也有一颗巨大的宽容心。他是一个了不起的人”。

---

毫无疑问，Aaron Swartz 是个天才。 创造 RSS 1.0 规则，开发 Web.py，参与 W3C 组织，创立 Infogami（后与 Reddit 合并），创立 Open Library，参与设计 Markdown 排版语言。程序员，作家，互联网活动家。
在 26 岁，他的成就足以使我们许多人掩面羞愧。 毫无疑问，Aaron Swartz 是个好人。 他的好朋友 Lawrence Lessig 说，“在他的一生中，Aaron 从未做过任何 ‘为赚钱’ 的事情……Aaron 只为公益而工作，一贯如此（至少他是这样想的）。他聪明，有趣。一个天才儿童。一个灵魂、一个良心、一个问题的源头，他曾经让我百万次问自己：Aaron 会这样想？”
曾和他一起开发了 MarkDown 的 John Gruber 说，“Aaron 有着非常出众的才智 ——再说一次，非常聪明的头脑——但同时也有一颗巨大的宽容心。他是一个了不起的人”。

---

文本块

语法1：

在连续几行的文本开头加入2个Tab或者4个空格。（不推荐，实际上tab与空格有些渲染引擎并不支持)

<tab><tab>欢迎到访
<space><space><space><space>很高兴见到您
<空格><空格><空格><空格>祝您生活愉快

欢迎到访
很高兴见到您
祝您生活愉快

语法2

使用一对各三个的反引号也就是你电脑上esc键下的按键，位于1按键左边： `

反引号引用文本块

欢迎到访
我是C++码农
你好呀

当然你也可以在代码块中使用各种语言标记，如果你的markdown引擎足够强大，会渲染出不同效果

渲染代码块

文字高亮

文字高亮功能能使行内部分文字高亮，使用一对反引号。 一般我们会在一些关键位置加亮提示用户，也可以做网站的tag标签
语法：

`linux` `网络编程` `socket` `epoll` 

效果：linux 网络编程 socket epoll

换行

有一些引擎在渲染机制上是有出入的，直接回车不能换行，
但是你可以在上一行文本后面补两个空格，
这样下一行的文本就换行了。

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

也能实现换行效果，不过这个行间距有点大。

斜体、粗体、删除线

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

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

图片

基本格式：

![alt](URL title)

alt和title即对应HTML中的alt和title属性（都可省略）：

• alt表示图片显示失败时的替换文本
• title表示鼠标悬停在图片时的显示文本（注意这里要加引号）

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

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

#	语法	效果
1		baidu
2	![][foryou]

注意例2的写法使用了URL标识符的形式，在链接一节有介绍。

在文末有foryou的定义：

[foryou]:https://github.com/guodongxiaren/ImageCache/raw/master/Logo/foryou.gif

链接

链接外部URL

#	语法	效果
1	[我的博客](http://blog.csdn.net/guodongxiaren "悬停显示")	我的博客
2	[我的知乎][zhihu]	我的知乎

语法2由两部分组成：

• 第一部分使用两个中括号，[ ]里的标识符（本例中zhihu），可以是数字，字母等的组合，标识符上下对应就行了（姑且称之为URL标识符）
• 第二部分标记实际URL。

使用URL标识符能达到复用的目的，一般把全文所有的URL标识符统一放在文章末尾，这样看起来比较干净。

URL标识符是我起的名字，不知道是否准确。囧。。

链接本仓库里的URL

语法	效果
[我的简介](/example/profile.md)	我的简介
[Book](./Book)	Book

图片链接

给图片加链接的本质是混合图片显示语法和普通的链接语法。普通的链接中[ ]内部是链接要显示的文本，而图片链接[ ]里面则是要显示的图片。
直接混合两种语法当然可以，但是十分啰嗦，为此我们可以使用URL标识符的形式。

#	语法	效果
1	[[图片上传失败...(image-ea9c0f-1531809400967)]	[[图片上传失败...(image-562f47-1531809400967)]
2	[[图片上传失败...(image-2b77ee-1531809400967)]][zhihu]	[图片上传失败...(image-d8a872-1531809400967)]
3	[![csdn-logo]][csdn]	![csdn-logo]

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

本文URL标识符都放置于文末

锚点

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

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

不过要注意，标题中的英文字母都被转化为小写字母了。

以前GitHub对中文支持的不好，所以中文标题不能正确识别为锚点，但是现在已经没问题啦！

列表

无序列表

• 昵称：果冻虾仁

• 别名：隔壁老王

• 英文名：Jelly

多级无序列表

• 编程语言
  • 脚本语言
    • Python

有序列表

一般效果

就是在数字后面加一个点，再加一个空格。不过看起来起来可能不够明显。
面向对象的三个基本特征：

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

多级有序列表

和无序列表一样，有序列表也有多级结构：

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

复选框列表

• [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

int main(int argc, char *argv[]) //C

echo "hello GitHub" #Bash

document.getElementById("myH1").innerHTML="Welcome to my Homepage"; //javascipt

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	百度

表情

Github的Markdown语法支持添加emoji表情，输入不同的符号码（两个冒号包围的字符）可以显示出不同的表情。

比如:blush:，可以显示:blush:。

具体每一个表情的符号码，可以查询GitHub的官方网页http://www.emoji-cheat-sheet.com。

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

diff语法

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

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

效果如下：

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

---