Markdown语法参考-基础与高级用法

Markdown 是一种轻量级标记语言,它允许人们“使用易读易写的纯文本格式编写文档，然后转换成有效的 XHTML（或者 HTML）文档”。被广泛应用于博客，网页与技术文档中

为什么选择 Markdown

• 它基于纯文本，方便修改和共享；
• 几乎可以在所有的文本编辑器中编写；
• 有众多编程语言的实现，以及应用的相关扩展；
• 在 GitHub 等网站中有很好的应用；
• 很容易转换为 HTML 文档或其他格式；
• 适合用来编写文档、记录笔记、撰写文章。

Markdown 语法

段落与换行

1. 段落的前后必须是空行：空行指的是行内什么都没有，或者只有空白符（空格或制表符).相邻两行文本，如果中间没有空行 会显示在一行中（换行符被转换为空格）

2. 如果需要在段落内加入换行（<br>）：可以在前一行的末尾加入至少两个空格,然后换行写其它的文字

3. Markdown 中的多数区块都需要在两个空行之间。

标题

一般用对称的 # 包括文本，或者只在左边使用 #。例如下面的语句：

#### 标题4 ####

#####  标题5

标题4

标题5

其中加几个#表示几级标题，在#符号内侧一般会加上空格

引用

1. 引用内容

在段落或其他内容前使用 > 符号，就可以将这段内容标记为 ‘引用’ 的内容：

>引用内容

引用内容

2. 多行引用

多行引用可以在每行前加 >,也可以仅在第一行使用 >，后面相邻的行即使省略 >，也会变成引用内容。
如果引用内容需要换行， 可以在行尾添加两个空格，或者在引用内容中加一个空行，如下所示：

>如果引用内容需要换行，  
>可以在行尾添加两个空格
>
>或者在引用内容中加一个空行

列表

无序列表

* 可以使用 `*` 作为标记
+ 也可以使用 `+`
- 或者 `-`

上述语句的渲染结果为：

• 可以使用 * 作为标记

• 也可以使用 +

• 或者 -

有序列表

1. 有序列表以数字和 `.` 开始；
3. 数字的序列并不会影响生成的列表序列；
4. 但仍然推荐按照自然顺序（1.2.3...）编写。

上述语句的渲染结果为：

1. 有序列表以数字和 . 开始；
2. 数字的序列并不会影响生成的列表序列；
3. 但仍然推荐按照自然顺序（1.2.3…）编写。

嵌套(多层)列表

多层列表在符号或者序号前加上tab即可

1. 第一层
  + 1-1
  + 1-2
2. 无序列表和有序列表可以随意相互嵌套
  1. 2-1
  2. 2-2

1. 第一层

• 1-1
• 1-2

2. 无序列表和有序列表可以随意相互嵌套
3. 2-1
4. 2-2

代码

代码块

可以使用缩进来插入代码块，但是一般我们使用 ``````来包含多行代码
```
<p>code here</p>
```
上述语句的渲染结果为：

<p>code here</p>

代码高亮

在上面的代码块语法基础上，在第一组 ```之后添加代码的语言，如 ‘javascript’ 或 ‘js’，即可将代码标记为 JavaScript,同时可以将对应代码高亮
：
```js
window.addEventListener(‘load’, function() {
console.log(‘window loaded’);
});
```

window.addEventListener('load', function() {
  console.log('window loaded');
});

Markdown支持的语言与相应关键字有：

名称	关键字	调用的js	说明
AppleScript	applescript	shBrushAppleScript.js
ActionScript 3.0	actionscript3 , as3	shBrushAS3.js
Shell	bash , shell	shBrushBash.js
ColdFusion	coldfusion , cf	shBrushColdFusion.js
C	cpp , c	shBrushCpp.js
C#	c# , c-sharp , csharp	shBrushCSharp.js
CSS	css	shBrushCss.js
Delphi	delphi , pascal , pas	shBrushDelphi.js
diff&patch	diff patch	shBrushDiff.js	用代码版本库时,遇到代码冲突,其语法就是这个.
Erlang	erl , erlang	shBrushErlang.js
Groovy	groovy	shBrushGroovy.js
Java	java	shBrushJava.js
JavaFX	jfx , javafx	shBrushJavaFX.js
JavaScript	js , jscript , javascript	shBrushJScript.js
Perl	perl , pl , Perl	shBrushPerl.js
PHP	php	shBrushPhp.js
text	text , plain	shBrushPlain.js	就是普通文本.
Python	py , python	shBrushPython.js
Ruby	ruby , rails , ror , rb	shBrushRuby.js
SASS&SCSS	sass , scss	shBrushSass.js
Scala	scala	shBrushScala.js
SQL	sql	shBrushSql.js
Visual Basic	vb , vbnet	shBrushVb.js
XML	xml , xhtml , xslt , html	shBrushXml.js
Objective C	objc , obj-c	shBrushObjectiveC.js
F#	f# f-sharp , fsharp	shBrushFSharp.js
R	r , s , splus	shBrushR.js
matlab	matlab	shBrushMatlab.js
swift	swift	shBrushSwift.js
GO	go , golang	shBrushGo.js

上述表格应该包括所有的常使用的代码语言，但肯定不包括所有的语言，如有缺失欢迎指出

分隔线

可以在一行中使用三个或更多的 *、- 或 _ 来添加分隔线：

***
------
___

---

超链接

格式为[link text](URL ‘title text’)

[Google](http://www.google.com/)

上述语句的渲染结果为：
Google

同时也可以创建指向本地文件的链接：

[icon.png](./images/icon.png)

图像

插入图片的语法和插入超链接的语法基本一致，只是在最前面多一个 !.

![GitHub](https://avatars2.githubusercontent.com/u/3265208?v=3&s=100 "GitHub,Social Coding")

强调

1. 使用 * * 或 _ _ 包括的文本会被转换为 <em></em> ，通常表现为斜体：

这是用来 *演示* 的 _文本_

这是用来 演示 的 文本

2. 使用 ** ** 或 __ __ 包括的文本会被转换为 <strong></strong>，通常表现为加粗：

这是用来 **演示** 的 __文本__

这是用来 演示 的 文本

3. 用来包括文本的 * 或 _ 内侧不能有空白，否则 * 和 _ 将不会被转换（不同的实现会有不同的表现）：

这是用来 * 演示* 的 _文本 _

这是用来 * 演示* 的 _文本 _

4. 如果需要在文本中显示成对的 * 或 _，可以在符号前加入 (转义字符) 即可：

这是用来 \*演示\* 的 \_文本\_

这是用来 *演示* 的 _文本_

5. *、**、_ 和 __ 都必须 成对使用 。

Markdown字符转义

反斜线（\）用于插入在 Markdown 语法中有特殊作用的字符。

这是用来 *演示* 的 _文本_

这是用来 \*演示\* 的 \_文本\_

第一句结果出来的结果为：
这是用来 演示 的 文本
而第二句的结果为:
这是用来 *演示* 的 _文本_

这些需要转义的字符包括：

\
`
*
_
{}
[]
()
#
+
-
.
!

删除线

这就是 ~~删除线~~

这就是 删除线

表格

单元格和表头

使用 | 来分隔不同的单元格，使用 - 来分隔表头和其他行：

name | age
---- | ---
LearnShare | 12
Mike |  32

name	age
LearnShare	12
Mike	32

为了美观，可以使用空格对齐不同行的单元格，并在左右两侧都使用 | 来标记单元格边界：

|    name    | age |
| ---------- | --- |
| LearnShare |  12 |
| Mike       |  32 |

name	age
LearnShare	12
Mike	32

为了使 Markdown 更清晰，| 和 - 两侧需要至少有一个空格（最左侧和最右侧的 | 外就不需要了）。

对齐

在表头下方的分隔线标记中加入 :，即可标记下方单元格内容的对齐方式：

• :— 代表左对齐
• :–: 代表居中对齐
• —: 代表右对齐

| left | center | right |
| :--- | :----: | ----: |
| aaaa | bbbbbb | ccccc |
| a    | b      | c     |

left	center	right
aaaa	bbbbbb	ccccc
a	b	c

如果不使用对齐标记，单元格中的内容默认左对齐；表头单元格中的内容会一直居中对齐（不同的实现可能会有不同表现）。

在表格单元格里换行

借助于 HTML 里的
实现。

示例代码：

| Header1 | Header2                          |
|---------|----------------------------------|
| item 1  | 1. one<br />2. two<br />3. three |

示例效果：

Header1	Header2
item 1	1. one 2. two 3. three

在表格单元格里加入空格

直接在 Markdown 里用空格和 Tab 键缩进在渲染后会被忽略掉，需要借助 HTML 转义字符在行首添加空格来实现，  代表半角空格，  代表全角空格

| Header1 | Header2                          |
|---------|----------------------------------|
|     | one

Header1	Header2
	one

同理，这个方法可以在任何需要添加空格和缩进的地方使用

任务清单

- [ ] Eat
- [x] Code
  - [x] HTML
  - [x] CSS
  - [x] JavaScript
- [ ] Sleep

• Eat
• Code
  • HTML
  • CSS
  • JavaScript
• Sleep

添加emoji

更多可用 Emoji 代码参见 https://www.webpagefx.com/tools/emoji-cheat-sheet/

我和我的小伙伴们都笑了。:smile:

我和我的小伙伴们都笑了。😄

图文混排

使用 标签来贴图，然后指定 align 属性。

示例代码：

<img align="right" src="https://avatars2.githubusercontent.com/u/3265208?v=3&s=100 "/>

这是一个示例图片。

图片显示在 N 段文字的右边。

N 与图片高度有关。

刷屏行。

刷屏行。

到这里应该不会受影响了，本行应该延伸到了图片的正下方，所以我要足够长才能确保不同的屏幕下都看到效果。

这是一个示例图片。

图片显示在 N 段文字的右边。

N 与图片高度有关。

刷屏行。

刷屏行。

到这里应该不会受影响了，本行应该延伸到了图片的正下方，所以我要足够长才能确保不同的屏幕下都看到效果。

控制图片大小和位置

标准的 Markdown 图片标记 无法指定图片的大小和位置，只能依赖默认的图片大小，默认居左。

而有时候源图太大想要缩小一点，或者想将图片居中，就仍需要借助 HTML 的标签来实现了。图片居中可以使用

标签加 align 属性来控制，图片宽高则用 width 和 height 来控制。

示例代码：

**图片默认显示效果：**

![](https://imgconvert.csdnimg.cn/aHR0cHM6Ly9yYXcuZ2l0aHVidXNlcmNvbnRlbnQuY29tL216bG9naW4vbXpsb2dpbi5naXRodWIuaW8vbWFzdGVyL2ltYWdlcy9wb3N0cy9tYXJrZG93bi9kZW1vLnBuZw?x-oss-process=image/format,png)

**加以控制后的效果：**

<div align="center"><img width="65" height="75" src="https://imgconvert.csdnimg.cn/aHR0cHM6Ly9yYXcuZ2l0aHVidXNlcmNvbnRlbnQuY29tL216bG9naW4vbXpsb2dpbi5naXRodWIuaW8vbWFzdGVyL2ltYWdlcy9wb3N0cy9tYXJrZG93bi9kZW1vLnBuZw?x-oss-process=image/format,png"/></div>

图片默认显示效果：

加以控制后的效果：

文字颜色、大小、字体设置

颜色

浅红色文字：<font color="#dd0000">浅红色文字：</font><br /> 
深红色文字：<font color="#660000">深红色文字</font><br /> 
浅绿色文字：<font color="#00dd00">浅绿色文字</font><br /> 
深绿色文字：<font color="#006600">深绿色文字</font><br /> 
浅蓝色文字：<font color="#0000dd">浅蓝色文字</font><br /> 
深蓝色文字：<font color="#000066">深蓝色文字</font><br /> 
浅黄色文字：<font color="#dddd00">浅黄色文字</font><br /> 
深黄色文字：<font color="#666600">深黄色文字</font><br /> 
浅青色文字：<font color="#00dddd">浅青色文字</font><br /> 
深青色文字：<font color="#006666">深青色文字</font><br /> 
浅紫色文字：<font color="#dd00dd">浅紫色文字</font><br /> 
深紫色文字：<font color="#660066">深紫色文字</font><br /> 

浅红色文字：浅红色文字：

深红色文字：深红色文字

浅绿色文字：浅绿色文字

深绿色文字：深绿色文字

浅蓝色文字：浅蓝色文字

深蓝色文字：深蓝色文字

浅黄色文字：浅黄色文字

深黄色文字：深黄色文字

浅青色文字：浅青色文字

深青色文字：深青色文字

浅紫色文字：浅紫色文字

深紫色文字：深紫色文字

采用的是RGB颜色
这里有个对照：
http://www.114la.com/other/rgb.htm
可以选择你想要的颜色对应的RGB值。

大小

size为1：<font size="1">size为1</font><br /> 
size为2：<font size="2">size为2</font><br /> 
size为3：<font size="3">size为3</font><br /> 
size为4：<font size="4">size为4</font><br /> 
size为10：<font size="10">size为10</font><br /> 

效果如下：

size为1：size为1

size为2：size为2

size为3：size为3

size为4：size为4

size为10：size为10

字体

<font face="黑体">我是黑体字</font>
<font face="宋体">我是宋体字</font>
<font face="微软雅黑">我是微软雅黑字</font>
<font face="fantasy">我是fantasy字</font>
<font face="Helvetica">我是Helvetica字</font>

效果如下：

我是黑体字
我是宋体字
我是微软雅黑字
我是fantasy字
我是Helvetica字

背景色

<table><tr><td bgcolor=#FF00FF>背景色的设置是按照十六进制颜色值：#7FFFD4</td></tr></table>
<table><tr><td bgcolor=#FF83FA>背景色的设置是按照十六进制颜色值：#FF83FA</td></tr></table>
<table><tr><td bgcolor=#D1EEEE>背景色的设置是按照十六进制颜色值：#D1EEEE</td></tr></table>
<table><tr><td bgcolor=#C0FF3E>背景色的设置是按照十六进制颜色值：#C0FF3E</td></tr></table>
<table><tr><td bgcolor=#54FF9F>背景色的设置是按照十六进制颜色值：#54FF9F</td></tr></table>

背景色的设置是按照十六进制颜色值：#7FFFD4

背景色的设置是按照十六进制颜色值：#FF83FA

背景色的设置是按照十六进制颜色值：#D1EEEE

背景色的设置是按照十六进制颜色值：#C0FF3E

背景色的设置是按照十六进制颜色值：#54FF9F

格式化表格

表格在渲染之后很整洁好看，但是在文件源码里却可能是这样的：

|Header1|Header2|
|---|---|
|a|a|
|ab|ab|
|abc|abc|

在各种编辑器里有为 Markdown 提供了表格格式化功能，比如我使用 Vim 编辑器，就有 vim-table-mode 插件，它能帮我自动将表格格式化成这样：

| Header1 | Header2 |
|---------|---------|
| a       | a       |
| ab      | ab      |
| abc     | abc     |

是不是看着舒服多了？

如果你不使用 Vim，也没有关系，比如 Atom 编辑器的 markdown-table-formatter 插件，Sublime Text 3 的 MarkdownTableFormatter 等等，都提供了类似的解决方案。

自动维护目录

有时候维护一份比较长的文档，希望能够自动根据文档中的标题生成目录（Table of Contents），并且当标题有变化时自动更新目录，能减轻工作量，也不易出错。

如果你使用 Vim 编辑器，那可以使用插件 vim-markdown-toc 来帮你完美地解决此事：

插件地址：https://github.com/mzlogin/vim-markdown-toc

参考文档：
https://mazhuang.org/2017/09/01/markdown-odd-skills/#%E5%9B%BE%E6%96%87%E6%B7%B7%E6%8E%92
http://xianbai.me/learn-md/index.html

个人公众号：Smilecoc的杂货铺，欢迎关注！