MARKDOWN语法实用指南
何为Markdown
对于HTML(超文本标记语言)一般人不会陌生,同样地,Markdown也属于标记语言的范畴。HTML语言主要是为了定义一个网页的结构和内容,而Markdown语言主要是赋予文本格式,Markdown更应该属于一种格式语言。
HTML中的标记在Markdown中得到了完美支持,但是在使用块状元素标签(div、table、pre、p、ul、ol等)时,必须在前后加上空行与其他内容隔开,并且开始标签和结束标签不能用制表符或空格来缩进。注意:在HTML块状元素标签内的Markdown格式语法将不会被处理,而在HTML行内元素标签内的Markdown格式语法将会得到正常处理。
例如:
<div>
*Markdown强调,但没有效果*
</div>
Html中的实体字符
Html中实体字符分为两种:HTML预留的字符(例如 <和‘>’定义标签的开始和结束,还有‘&’定义字符实体的开始)和键盘上没有的字符(例如版权©、欧元€等)。
Markdown中对这些实体字符能够进行自动识别并将其转化为实体字符的实体名称,而对于实体字符的字符名称和字符编号Markdown则不会进行处理。
例如以下代码:
AT&T
会被转化为
AT&T
©
还是
©
显示结果(原型) | 描述 | 实体名称 | 实体编号 |
---|---|---|---|
空格 | |   | |
< | 小于号 | < | < |
> | 大于号 | > | > |
& | 和号 | & | & |
" | 引号 | " | " |
' | 撇号 | ' | ' |
¢ | 分(cent) | ¢ | ¢ |
£ | 磅(pound) | £ | £ |
¥ | 元(yen) | ¥ | ¥ |
€ | 欧元(euro) | € | € |
© | 版权 | © | © |
' | 撇号 | ' | ' |
® | 注册商标 | ® | ® |
™ | 商标 | ™ | ™ |
× | 乘号 | × | × |
÷ | 除号 | ÷ | ÷ |
注意:在code范围内,不论是行内元素还是块状元素,&和<都会被自动转化为&和<。这样的特性可以使我们很容易在Markdown写HTML code,而我们在写HTML文档时,必须要把所有的<和&都换成实体字符形式,才能在其中写入HTML code。
块状元素
段落和换行
一个Markdown段落是由一个或多个连续的文本组成的,它的前后要有一个以上的空行(空行就是显示起来是空的就是空行,就算其中有空格和制表符还是被视为空行。)普通段落不该用空格和制表符缩进。
「由一个或多个连续的文本行组成」暗示了 Markdown 允许段落内的强迫换行(插入换行符),这个特性和其他大部分text-to-HTML 格式不一样(包括 Movable Type 的「Convert Line Breaks」选项),其它的格式会把每个换行符都转成
标签。
若你确实想依赖Markdown来插入'
’标签,在插入处先按两个以上的空格然后回车。这样使得Markdown中email式的区块引用和多段落的列表更容易使用换行来排版。
标题
Markdown支持类Setex和类Atx两种标题形式。
类Setex采用底线形式,利用’=’(最高级标题)和’-’(二级标题),如下:
这是最高级标题
==============
这是二级标题
------------
无论多少个’=’和’-’都是有效的。
类ATx形式则是在行首插入1到6个’#’,对应1到6级标题,如下:
# 这是 H1
## 这是 H2
###### 这是 H6
可以选择性地闭合类atx样式的标题,纯粹为了美观,行尾加上’#’且无论加上多少个’#’,都不影响标题的显示。
# 这是 H1 #
## 这是 H2 ##
###### 这是 H6 ###
块状引用
块状引用使用类似email中用’>’的引用方式,如下:
>我是引用我是引用我是引用我是引用我是引用,
>我是引用我是引用我是引用我是引用我是引用引用我是引用。
>引用我是引用引用我是引用引用我是引用引用我是引用,引用我是引用。
>
>引用我是引用引用我是引用引用我是引用引用我是引用引用我是引用,引用
>引用我是引用引用我是引用引用我是引用引用我是引用引用我是引用。
也可以只在整个段落的第一行前面加上’>’:
>我是引用我是引用我是引用我是引用我是引用,
我是引用我是引用我是引用我是引用我是引用引用我是引用。
引用我是引用引用我是引用引用我是引用引用我是引用,引用我是引用。
>引用我是引用引用我是引用引用我是引用引用我是引用引用我是引用,引用
引用我是引用引用我是引用引用我是引用引用我是引用引用我是引用。
区块引用可以嵌套(引用内的引用),只需根据层次加上相应数量的’>’:
>这是第一层引用
>
>>这是嵌套引用
>
>回到第一层引用
引用内的区块可以使用其他Markdown语法,例如标题、段落、列表等:
>## 这是一个标题。
>
>1. 这是第一行列表项。
>2. 这是第二行列表项。
>
>下面是例子代码:
>
> return shell.exec('hello python');
列表
列表分为有序和无序两种:
无序使用’*’号、’+’号和’-’号作为列表标记:
* 姓名
* 年龄
* 性别
等同于:
+ 姓名
+ 年龄
+ 性别
也等同于:
- 姓名
- 年龄
- 性别
有序列表则使用数字接着一个英文句点:
1. 姓名
2. 年龄
3. 性别
注意:列表项前面使用的数字并不影响输出的HTML结果,上面列表产生的HTML标记为:
<ol>
<li>姓名</li>
<li>年龄</li>
<li>性别</li>
</ol>
如果你的列表标记写成:
1. 姓名
1. 年龄
1. 性别
甚至是:
3. 姓名
1. 年龄
8. 性别
你会得到完全相同的HTML输出。你可以让Markdown文件的列表数字和输出的结果相同,也可以不用在意数字的正确性。
如果你不在意数字的正确性,建议第一个项目最好是从1.开始,因为Markdown未来可能会支持有序列表的start属性。
列表项目标记通常放在最左边,也可以缩进,最多3个空格,标记后面一定要跟着至少一个空格和制表符。
要让列表看起来漂亮,你可以把内容用固定的缩进整理好:
* 文字文字文字文字文字文字文字文字文字文字文字文字文字文字,
文字文字文字文字文字文字文字文字文字文字文字文字。
* 文字文字文字文字文字文字文字文字文字文字文字文字文字,文字
文字文字文字文字文字文字
列表项目间用空行分开,在输出HTML时会将项目内容用'标签'包起来,举例来说:
* 姓名
* 性别
会被转化为:
<ul>
<li>姓名</li>
<li>姓名</li>
</ul>
但是这个:
* 姓名
* 性别
会被转化为:
<ul>
<li>
<p>姓名</p>
</li>
<li>
<p>姓名</p>
</li>
</ul>
列表项目可以包含多个段落,每个项目下的段落必须缩进4个空格或1个制表符:
1 文字文字文字文字文字文字文字文字文字文字文字文字文字
文字文字文字文字文字文字文字文字文字
文字文字文字文字文字文字文字文字文字文字文字
文字文字文字文字文字文字文字文字,文字文字文字
文字文字文字文字文字文字文字文字
文字文字文字。
2 文字文字文字文字文字文字文字文字文字文字文字文字,
文字文字文字文字文字文字文字文字。
文字文字文字文字文字文字文字文字,文字文字文字文字
文字文字文字文字文字
按照上面每个段落每行都有缩进,会看起来更好看,但下面的方式也是有效的:
1 文字文字文字文字文字文字文字文字文字文字文字文字文字
文字文字文字文字文字文字文字文字文字
文字文字文字文字文字文字文字文字文字文字文字
文字文字文字文字文字文字文字文字,文字文字文字
文字文字文字文字文字文字文字文字
文字文字文字。
2 文字文字文字文字文字文字文字文字文字文字文字文字,
文字文字文字文字文字文字文字文字。
文字文字文字文字文字文字文字文字,文字文字文字文字
文字文字文字文字文字
如果要在列表项目内放引用,那'>'就需要缩进:
* 一个有块状引用的列表项:
>在列表项内的
>块状引用
如果要放代码区块,该区块必须缩进两次,也就是8个空格或是2个制表符:
* 一个列表项包含一个代码区块:
<代码在这>
注意:一不小心就可能产生项目列表,如下:
1997. 今年香港回归了。
也就是说,若是在行首出现数字-.-空白,要避免这种情况,必须要在句点前面加反斜杠。
1997\. 今年香港回归了。
代码区块
简单地缩进4个空格或是一个制表符,就可以定义一个代码区块。代码区块会一直持续到没有缩进的哪一行(或是文件结尾)例如:
这是一个普通的段落:
这是代码区块
Markdown会将上面的代码区块转化为:
<p>这是一个普通的段落:</p>
<pre><code>这是一个代码区块。
</code></pre>
代码区块每行的缩进(4个空格或一个制表符),都会被移除:
这是一个普通的段落:
这是代码区块,代码区块代码区块
代码区块
代码区块代码区块代码区块代码区块
代码区块
会转化为:
<p>这是一个普通段落:</p>
<pre>这是代码区块,代码区块代码区块
代码区块
代码区块代码区块代码区块代码区块
代码区块
</pre>
代码区块中,<
,>
和&
会被自动转化成HTML实体字符形式。我们插入HTML原始码,只需要复制粘帖,再加上缩进就可以了,剩下的交给Markdown。
<div class="footer">
©2016 版权所有
</div>
会被转化为:
<pre><code><div class="footer">
&copy;2016 版权所有
</div>
</code></pre>
在代码区块中,一般的markdown语法不会被转化,像是*
号还是*
号,这样使得我们很容易以Markdown语法撰写Markdown语法相关的文件。
分割线
在一行用3个以上的*
或-
或_
来建立一个分割线,行内不能有其他东西。你也可以在这些符号中间插入空格,下面每种写法都可以建立分割线:
* * *
***
******
- - -
————————————————
行内元素
链接
Markdown支持两种形式的链接语法:行内式和参考式。都用[文字]
来标记链接文字,并在方括号后面紧接着圆括号插入网址链接即可,用双引号把文字包起来可以形成链接的title属性,例如:
这是一个[百度首页](http://www.baidu.com/ "百度首页")行内链接。
[百度首页](http://www.baidu.com/)没有title属性。
会转化为:
<p>这是一个<a href="http://www.baidu.com/" title="Title">百度首页</a>行内链接。</p>
<p><a href="http://www.baidu.com/">百度首页</a>没有title属性。</p>
若是链接到同样主机的资源,可以使用相对路径:
文章[详情](/about/)更多信息。
会产生:
<p>文章<a href=/about/>详情</a>更多信息。</p>
参考式链接是在链接文字后面的括号后面再加上另一个方括号,第二个方括号里面要填入用以标识链接的标记:
这是一个参考样式的[链接][id]
可以选择性的在两个方括号中间加上一个空格:
这是一个参考样式的[链接] [id]
然后,在文件的任意处把这个链接的内容定义出来:
[id]: http://www.baidu.com/ "可选择性的标题"
链接内容的定义形式为:
- 方括号(前面可以选择性的至多加上三个空格缩进),里面输入链接标记
- 接着一个冒号
- 接着一个以上的空格或制表符
- 接着链接的网址
- 选择性的接着title内容,可以用单引号、双引号或是括弧包着
下面三种链接内容的定义都是相同的:
[id]: http://www.baidu.com/ "可选择性的标题"
[id]: http://www.baidu.com/ '可选择性的标题'
[id]: http://www.baidu.com/ (可选择性的标题)
** 注意: **Markdown.pl 1.0.1会忽略单引号括起来的链接title。
链接网址也可以用尖括号包起来:
[id]: <http://www.baidu.com/> "可选择性的标题"
如果网址太长,为了美观,可以将title属性放在下一行并且可以加上缩进
[id]: http://www.baidu.com/
"可选择性的标题"
网址定义只有在产生链接的时候用到,并不会直接出现在文件之中。
标识链接的标记可以有字母、数字、空白和标点符号,但是并不区分大小写,如下链接是一样的:
[link text] [a]
[link text] [A]
隐式链接标记功能让你可以省略指定链接标记,这种情况下,链接文字会被视为等同链接文字。在链接文字后面加上一个空的方括号,就可以实现隐式链接功能。如下:
[baidu][]
然后定义链接内容:
[baidu]: http://www.baidu.com/
由于链接文字可能包含空白,所以这种简化型的标记内也许会包含多个单词:
搜索[baidu home][]获取更多信息
接着定义链接内容:
[baidu home]: http://www.baidu.com/
链接内容可以放在文件中任何一个地方,可以放在段落的后面,也可以像注解一样放在文章的最后面。
以下参考式链接代码例子:
相比于[百度][1],我更喜欢[QQ][2]。
[1]: http://baidu.com/ "baidu"
[2]: http://qq.com/ "QQ"
按照隐式链接去写以上代码:
相比于[百度][],我更喜欢[QQ][]。
[百度]: http://baidu.com/ "Baidu"
[QQ]: http://qq.com "QQ"
上面两种写法都会产生下面的HTML代码:
<p>相比于<a href="http://baidu.com/" title="Baidu">百度</a>,我更喜欢
<a href="http://qq.com" title="QQ">QQ</a>。
</p>
同样的,用行内式链接样式写的Markdown代码如下:
相比于[百度](http://baidu.com/ "Baidu"),我更喜欢
[QQ](http://qq.com "QQ")
参考式链接可以让文本变得更易读,参考式链接相对于行内式链接和HTML原生a
链接,需要的字节更少。因为关于链接的元数据都被放在段落后面或者文章后面,所以阅读起来更流畅,不容易被打断。
强调
用*
包或_
围字词,会被转为<em>
。而用**
或者__
会被转为<strong>
。用什么符号开启标签,就要用什么符号结束标签。
** 注意: **如果你的强调符号两边都有空白,它们就只会被当成普通的符号。如果要在文字前后插入普通的星号或底线,你可以用反斜线:
\*前后的都有星号,但被反斜线转义了\*
行内代码块
用反引号包住行内代码块。如果要在代码内添加
,可以用多个反引号`````开启和结束代码区段。在代码区段的起始端后面和结束端前面,就可以在区段一开始就插入
`反引号:
`` `一开始就插入反引号`,就是这么任性。 ``
产生如下HTML代码:
<p><code>`一开始就插入反引号`,就是这么任性。</code></p>
在代码区段内&,<和>都会被自动转为HTML实体字符形式,这样插入HTML原始码很容易:
`<a>&`
会被转为:
<code><a>&</code>
因为markdown会自动识别HTML字符实体,为了写出字符实体,需要这样写:
`&`
被转为:
<code>&amp;</code>
图片
图片的添加方式也分为行内式和参考式:
行内式的图片语法:
![Alt text](/path/to/img.jpg "可选择的标题")
详细语法如下:
- 一个惊叹号
!
- 一个方括号,里面放上图片的替代文本
- 圆括号,里面放上图片的网址,还可以选择性地加上图片title属性
参考式的图片语法:
![Alt text][id]
id是图片参考的名称,图片参考的定义方式和链接的参考定义方式一样:
[id]: url/to/img "Optional title attribute"
若要指定图片的宽高以及其他属性,推荐使用HTML的<img>
标签。
其他
自动链接
所谓自动链接就是通过在网址和电子邮件地址前后加上尖括号,自动转为一个链接。如下:
<http://www.baidu.com/>
会被转为:
<a href="http://www.baidu.com/">http://www.baidu.com</a>
邮件地址的转化类似,只是Markdown会先做一个编码转化的过程,把文字字符转为16位码的HTML实体,这样防止一些不好的机器人收集邮件地址:
<address@example.com>
会被转为:
<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
&amp;#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
转义
Markdown可以通过在一些拥有特殊功能的字符前加反斜线\
,使其正常显示。例如:
\\哈哈\\\*嘻嘻\*
转为HTML:
\哈哈\*嘻嘻*
以下字符支持通过加反斜杠使其正常显示
\
反斜线*
星号#
井号_
底线{}
花括号[]
方括号()
括弧+
加号-
减号.
英文句点!
感叹号
本文参考了以下资料: