前言

GitHub 的 Markdown 语法在其标准的语法基础上做了扩充，称之为 GitHub Flavored Markdown 。简称 GFM 。  

GFM 有site-in issues,comments,pull requests等功能，它与标准的Markdown有一些区别，并增加了些新的扩展功能，在Github中，除了README文件外，issues 和 wiki 均支持 Markdown 语法。

注意：
不同的 Markdown引擎 均有可能做了不同的渲染处理，本文仅以Github常用的 Markdown 来做举例说明，

疑问解答:

提问 1:
　　我把大段文段复制到 MarkdownEditor.io 上进行重新编辑，再贴回 github 修改框后，发现格式依然是乱的，只不过由一种乱法变成了另一种乱法。

回答 1：
　　上网去查，发现GFM是一种独立于Markdown的语法。在一些语法的书写上，比如列表多重嵌套，并在其中多层插入注释字段时，语法与普通的　Markdown　语法还是有很大的差别的。之前学习Markdown的时候，虽然知道Markdown有很多变种语法，但是写的都只是一些简单的嵌套，并没有涉及三四重以上的嵌套，也没有在嵌套中插入注释，所以一直没觉得GFM和Mrakdown有什么区别。直到碰上了具体情况需要这种的复杂书写时，才暴露出了这个问题。

提问 2:
　　用GFM书写简单语法时，用两个空格键就能代替Tab。空格键和Tab键常常可以多打也没关系。于是我在多重嵌套的时候依然这么干。。然后就悲剧了。。T T

回答 2:
　　在书写GFM时想要不犯错，缩进必须要严格采用Tab键（Tab键会等于超级多个空格，远不止四个）。Tab键既不可以多打也不可以少打。

提问 3:
　　列表多重嵌套时，对其中某一项插入注释

回答 3:
　　如果注释句要与被注释的句项都是４个#字体大小的（注意：正常大小字体也会被当成前面加了4个#来识别），为了让转换器识别出这是两句从属关系的语句，则插入之前，该注释句要与被注释的句项间隔至少一行；如果注释句要与被注释的句项字体大小不一样，则可以不用空行。但是不论是哪种情况，该注释句都必须要比被注释的句项恰好多空一个Tab（只管敲Tab就好了，就算觉得每个Tab离得再宽，编辑器也会自动帮你识别清楚的；但是对列表树根进行注释时，该注释句 却不能 比被注释的句项多空一个Tab。。。没搞懂为什么会这样　T T ）

提问 4:
　　某些时候会把语法符号也跟着显示出来，或者一些语法转换成 H5 时错乱

回答 4:
　　可能是输入时，输入状态还是处于“中文”状态下。像空格，在“中文”状态下打出的一个空格距离和“英文”状态下打出的一个空格距离是不一样的。

提问 5:
　　因为Markdown系列的语法最后要被转换成h5，所有可以在 Markdown 系列(包括GFM)文本中插入h5字段，以作为Markdown系列语法的补充，来显示出更多的效果。然而当我想在GFM写的表格中的某个空里，插入h5的代码写的列表时，发现怎么也写不出这个效果。

回答 5:
　　H5 代码与 GFM 代码至少间隔一行。也就是说，Markdown系列文本的原语法字段和插入的h5字段是分开来识别的，其中前者会被转换。因而h5字段只能在全局文本的基础上插入，并不可以在原语法字段的代码中强行插入。

提问 6:
　　写语法时，经常会牵一发而动全身，语法错误累积多了之后，会给修改造成很大麻烦。因为任何一种显示出来的错误，都可能是多个语法错误的综合作用结果。

回答 6:
　　规范书写很重要！语法正确要从娃娃抓起！！

提问 7:
　　有时候在修改代码时，改了一个地方好像把前面字段的显示改过来了，改到后面又发现前面字段的显示重新乱了。或者是感觉后面字段的语法完全没问题，但是就是显示出来不对（比如　####　会一直被直接显示出来，或者三级列表项会一直被显示为二级列表项）

回答 7:
　　还是因为语法错误累积得太多，牵一发而动全身。还是那句，规范书写很重要！

提问 8:
　　连续７个 # 后，无法转换成更小号的字体

回答 8:
　　还是因为语法错误累积得太多，牵一发而动全身。还是那句，规范书写很重要！

提问 9:
　　输入时，发现刚刚从 句首 输入的一个单字符，闪了一下又消失了

回答 9:
　　把前一个句法的末位字符改成以　‘英文输入状态’　输入

横线示例

1
Markdown示例 --------------------

效果：

1
Markdown示例 ============

效果：

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

1
Markdown示例 ****************** 或 ---

效果：

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

标题

1
2
3
4
一级标题
====
二级标题
----
1
2
3
4
5
6
# 一级标题  
## 二级标题  
### 三级标题  
#### 四级标题  
##### 五级标题  
###### 六级标题

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

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

<center>居中渲染</center>

居中渲染

文本

换行

实现方式一

有一些引擎在渲染机制上是有出入的，直接回车不能换行，  
但是你可以在上一行文本后面补两个空格，
这样下一行的文本就换行了。
或者就是在两行文本直接加一个空行。
也能实现换行效果，不过这个行间距有点大。

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

实现方式二

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

Markdown示例

1
《爱情公寓》是上海电影集团公司出品，<br>上海高格影视制作有限公司承制的都市青春喜剧，由汪远编剧、韦正执导，陈赫、娄艺潇、孙艺洲、李金铭、邓家佳、王传君、金世佳、赵霁、李佳航、赵文琪领衔主演。

显示结果：
《爱情公寓》是上海电影集团公司出品，
上海高格影视制作有限公司承制的都市青春喜剧，由汪远编剧、韦正执导，陈赫、娄艺潇、孙艺洲、李金铭、邓家佳、王传君、金世佳、赵霁、李佳航、赵文琪领衔主演。

文本块

语法1：

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

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

语法2

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

反引号引用文本块

1
2
3
欢迎到访
我是Tamsiree
你好呀

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

文字高亮

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

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

效果：linux 网络编程 socket epoll

斜体、粗体、删除线

语法效果

1
*斜体1*

斜体1

1
_斜体2_

斜体2

1
**粗体1**

粗体1

1
__粗体2__

粗体2

1
这是一个 ~~删除线~~

这是一个 删除线

1
***斜粗体1***

斜粗体1

1
___斜粗体2___

斜粗体2

1
***~~斜粗体删除线1~~***

斜粗体删除线1

1
~~***斜粗体删除线2***~~

斜粗体删除线2

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

图片

基本格式：

1
![alt](URL title)

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

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

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

1
 https://cdn.jsdelivr.net/gh/Tamsiree/Assets@master/DeskTop/miku.png

语法效果

1
![miku](https://cdn.jsdelivr.net/gh/Tamsiree/Assets@master/DeskTop/miku.png)

miku

链接

链接外部URL

语法效果

1
[技术博客](https://tamsiree.github.io/ "悬停显示")

技术博客

锚点

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

语法效果

1
[回到顶部](#)

回到顶部

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

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

列表

无序列表

  • 昵称：果夏虾仁

  • 别名：隔壁老王

  • 英文名：Jelly

多级无序列表

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

有序列表

一般效果

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

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

多级有序列表

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

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

复选框列表

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

您可以使用这个功能来标注某个项目各项任务的完成情况。

Tip:

在GitHub的issue中使用该语法是可以实时点击复选框来勾选或解除勾选的，而无需修改issue原文。

块引用

常用于引用文本

“端”（endian）的起源
以下是Jonathan Swift在1726年关于大小端之争历史的描述：
“……下面我要告诉你的是，Lilliput和Blefuscu这两大强国在过去36个月里一直在苦战。战争开始是由于以下的原因：我们大家都认为，吃鸡蛋前，原始的方法是打破鸡蛋较大的一端，可是当今的皇帝的祖父小时候吃鸡蛋，一次按古法打鸡蛋时碰巧将一个手指弄破了，因此他的父亲，当时的皇帝，就下了一道敕令，命令全体臣民吃鸡蛋时打破较小的一端，违令者重罚。”

块引用有多级结构

数据结构

树

二叉树

平衡二叉树

满二叉树

代码高亮

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

Markdown编辑器的代码块在识别上需要一些特别的处理，要加上对应的关键字才可以识别出各种语言，再以不同形式的高亮色来标记

名称 关键词
CSS css
PHP php
SQL sql
C c , cpp
Java java
Scala scala
Swift swift
matlab matlab
Groovy groovy
R r , s , splus
GO go , golang
text text , plain
Python py , python
Erlang erl , erlang
JavaFX jfx , javafx
Perl perl , pl , Perl
VisualBasic vb , vbnet
Shell sh , bash , shell
SASS & SCSS sass , scss
AppleScript applescript
diff & patch diff patch
F# f# , f-sharp , fsharp
Objective C objc , obj-c
ColdFusion coldfusion , cf
C# c# , c-sharp , csharp
Delphi delphi , pascal , pas
Ruby ruby , rails , ror , rb
XML xml , xhtml , xslt , html
JavaScript js , jscript , javascript
ActionScript 3.0 actionscript3 , as3

示例

1
2
//java
public static void main(String[]args){} 
1
2
3
4
5
6
7
8
9
10
11
12
dependencies {
	//基础工具库
	implementation "com.github.tamsiree.RxTool:RxKit:2.3.9"
	//UI库
	implementation "com.github.tamsiree.RxTool:RxUI:2.3.9"
	//相机库
	implementation "com.github.tamsiree.RxTool:RxCamera:2.3.9"
	//功能库（Zxing扫描与生成二维码条形码 支付宝 微信）
	implementation "com.github.tamsiree.RxTool:RxFeature:2.3.9"
	//ArcGis For Android工具库（API：100.1以上版本）
	implementation "com.github.tamsiree.RxTool:RxArcGisKit:2.3.9"
}
1
2
//c    
int main(int argc, char *argv[]) 
1
2
#bash
echo "hello GitHub" 
1
2
//javascript
document.getElementById("myH1").innerHTML="Welcome to my Homepage"; 
1
2
//cpp
string &operator+(const string& A,const string& B)

表格

表头1 表头2
表格单元 表格单元
表格单元 表格单元

表格对齐

表格可以指定对齐方式

左对齐 居中 右对齐
左对齐 居中 右对齐

混合其他语法

表格单元中的内容可以和其他大多数GFM语法配合使用，如：

使用普通文本的删除线，斜体等效果

名字 描述
Help Display the help window.
Close Closes a window

表格中嵌入图片（链接）

图片 描述
miku miku

表情

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

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

：blush： —–> 😊

具体每一个表情的符号码，可以查询GitHub的官网 官网。

但是这个网页每次都打开奇慢。。所以我整理到了本博客中，大家可以直接在此查看 [Markdown内使用Emoji表情]。

diff语法

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

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

效果如下：

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

补充部分

文本添加下划线

Markdown 并无下划线的原生语法，因为会和链接的默认样式产生混淆。

  • 方法1：使用行内 HTML的 <u></u> 标签可以快速添加下划线，但是
    HTML5 规范建议开发者尽量使用其他元素替代 u 元素。而且使用行内 HTML的 <u></u>的下划线很难自定义其他效果，比如颜色
1
<u>Markdown行内文字</u>

效果：
Markdown行内文字

  • 方法2（推荐）：由于方案1的不完美，因此我个人建议那些喜欢高颜值排版的朋友，可以使用html的span标签、设置行内CSS的border-bottom属性 来添加下划线。这种方式自定义程度最高。
1
<span style="border-bottom:2px dashed blue;">Markdown行内文字</span>

效果：
Markdown行内文字

to be continued…