#Mark Down语法 1.0.1
[TOC]
##宗旨
Markdown 是一种轻量级标记语言,能将文本换成有效的XHTML(或者HTML文档,它的目标是实现易读易写,成为一种适用于网络的书写语言。
**注意:上一行有没有空行,对md把md文件转为html很关键**
##兼容 HTML
Markdown 不是想要取代 HTML,甚至也没有要和它相近,它的语法种类很少,只对应 HTML 标记的一小部分。
Markdown 的理念是,能让文档更容易读、写和随意改。
HTML 是一种发布的格式,Markdown 是一种书写的格式。就这样,Markdown的格式语法只涵盖纯文本可以涵盖的范围。
不在 Markdown 涵盖范围之内的标签,都可以直接在文档里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown;只要直接加标签就可以了。
要制约的只有一些 HTML 区块元素――比如 ``` <div>、<table>、<pre>、<p> ```等标签,必须在前后加上空行与其它内容区隔开,还要求它们的开始标签与结尾标签不能用制表符或空格来缩进。Markdown 的生成器有足够智能,不会在 HTML 区块标签外加上不必要的 ```<p>``` 标签。
例子如下,在 Markdown 文件里加上一段 HTML 表格:
这是一个普通段落。
```
<table>
<tr>
<td>Foo</td>
</tr>
</table>
```
这是另一个普通段落。
请注意,在 HTML 区块标签间的 Markdown 格式语法将不会被处理。比如,你在 HTML 区块内使用 Markdown 样式的*强调*会没有效果。
HTML 的区段(行内)标签如 `<span>、<cite>、<del>` 可以在 Markdown 的段落、列表或是标题里随意使用。依照个人习惯,甚至可以不用 Markdown 格式,而直接采用 HTML 标签来格式化。举例说明:如果比较喜欢 HTML 的 `<a>或 <img> `标签,可以直接使用这些标签,而不用 Markdown 提供的链接或是图像标签语法。
和处在 HTML 区块标签间不同,Markdown 语法在 HTML 区段标签间是有效的。
##特殊字符自动转换
markdown会对Html里的两个字符进行转换,是< 和 & ,要额外注意一下。
##区块元素
###段落和换行
1.建议在每个段落的前后加上一行以上的空行
2.在md文件中的一个回车换行,不等于在对应的html中加入了`<br/>`,这点要注意,如果需要强制换行,要打两个及以上的空格,一个回车;或者使用`</br>标签`
###标题
支持两种标题语法:类Setext和atx形式
```
Setext:
This is an H1
=============
This is an H2
-------------
atx:插入1-6个#,如果为了美观,后面也可以插入对应个数的#
# 这是 H1
## 这是 H2
###### 这是 H6
```
###区块引用 Blockquotes (左侧有一个竖线)
Markdown 标记区块引用是使用类似 email 中用 > 的引用方式。如果你还熟悉在 email 信件中的引言部分,你就知道怎么在 Markdown 文件中建立一个区块引用,那会看起来像是你自己先断好行,然后在每行的最前面加上 >
例如:
```
> ## 这是一个标题。
>
> 1. 这是第一行列表项。
> 2. 这是第二行列表项。
>
> 给出一些例子代码:
>
> return shell_exec("echo $input | $markdown_script");
```
###列表
1.无序列表:使用星号*、加号+或是减号-作为列表标记。要注意的是:
* 标记号右边必须有空格,且标记号左侧的空格不能超过3个空格,否则会认为是代码区块。
* 如果上一行不是空行,也不会被认为是代码区块,因为按md标准,需要有空行,同时,也不会被认为是标记,因为按md标准,也是需要空行的
* 记得在第一个标记的上一行,要输入两个空格加一个回车
2.有序列表:使用数字接着一个英文句点做为开发。要注意的是:
* 标记号右边必须有空格,且标记号左侧的空格不能超过3个空格,否则会认为是代码区块。
* 如果上一行不是空行,也不会被认为是代码区块,因为按md标准,需要有空行,同时,也不会被认为是标记,因为按md标准,也是需要空行的
* 记得在第一个标记的上一行,要输入两个空格加一个回车
* 即使在md文件中,序号是错的,在html中也会自动修改为正确的
* 如果碰到 1990.1.1这种被误转成列表了,可以在句点之前加上反斜线。`1986\.`
列表中:如果想在列表内部加入引用,则 > 就需要缩进,如果要放代码区块的话,该区块就需要缩进两次,也就是 8 个空格或是 2 个制表符
###代码区块
和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块,通常这些区块我们并不希望它以一般段落文件的方式去排版,而是照原来的样子显示,Markdown 会用 `<pre> `和 `<code>`标签来把代码区块包起来。
要在 Markdown 中建立代码区块很简单,只要简单地缩进 4 个空格或是 1 个制表符就可以
这个每行一阶的缩进(4 个空格或是 1 个制表符),都会被移除。一个代码区块会一直持续到没有缩进的那一行(或是文件结尾)。
例如:
这是一个普通段落:
这是一个代码区块。
Markdown 会转换成:
<p>这是一个普通段落:</p>
<pre><code>这是一个代码区块。
</code></pre>
如果已经有制表符或空格,被认为是代码区块了,此时再打间隔符,也会输出间隔符。
###分隔线
可以在一行中用三个以上的星号、减号、底线来建立一个分隔线,行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线。(上一行不需要为空,比如下面的示例就可生效)
- - -
* * *
___
###链接
Markdown 支持两种形式的链接语法: 行内式和参考式两种形式。
不管是哪一种,链接文字都是用 [方括号] 来标记。
####行内式
要建立一个行内式的链接,只要在方块括号后面紧接着圆括号并插入网址链接即可,如果你还想要加上链接的 title 文字,只要在网址后面,用双引号把 title 文字包起来即可,例如:
This is [an example](http://example.com/ "Title") inline link.
[This link](http://example.net/) has no title attribute.
如果你是要链接到同样主机的资源,你可以使用相对路径:
See my [About](/about/) page for details.
####参考式
参考式的链接是在链接文字的括号后面再接上另一个方括号,而在第二个方括号里面要填入用以辨识链接的标记。
链接内容定义的形式为:
* 方括号(前面可以选择性地加上至多三个空格来缩进),里面输入链接文字
链接辨别标签可以有字母、数字、空白和标点符号,但是并不区分大小写,因此下面两个链接是一样的:
* 接着一个冒号
* 接着一个以上的空格或制表符
* 接着链接的网址
* 选择性地接着 title 内容,可以用单引号、双引号或是括弧包着
例如:
[foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ 'Optional Title Here'
有一个已知的问题是 Markdown.pl 1.0.1 会忽略单引号包起来的链接 title。
[foo]: http://example.com/ (Optional Title Here)
[id]: <http://example.com/> "Optional Title Here"
以上四种情况相同
隐式链接标记功能让你可以省略指定链接标记,这种情形下,链接标记会视为等同于链接文字,要用隐式链接标记只要在链接文字后面加上一个空的方括号。
如可以将:
I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"
改写为
I get 10 times more traffic from [Google][] than from
Yahoo][] or [MSN][].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"
其中,方括号里面的链接辨别标签里,可以加上空格。
###强调(斜体及粗体)
Markdown 使用星号(*)和底线(_)作为标记强调字词的符号,被 * 或 _ 包围的字词会被转成用 `<em>` 标签包围,用两个 * 或 _ 包起来的话,则会被转成 `<strong>`,例如:
*single asterisks*
_single underscores_
**double asterisks**
__double underscores__
会转成:
<em>single asterisks</em>
<em>single underscores</em>
<strong>double asterisks</strong>
<strong>double underscores</strong>
强调也可以直接插在文字中间,但是如果 * 和 _ 两边都有空白的话,它们就只会被当成普通的符号。
如果要在文字前后直接插入普通的星号或底线,可以用反斜线,如:
\*this text is surrounded by literal asterisks\*
###代码区块及高亮
####行内代码块
在行内,某些字符是代码块的话,用一个间隔符来标记,它会自动转为`<code>`标签来标记,即键盘上1左边的那个键(英文状态下)
例如:
Use the `printf()` function.
会产生:
<p>Use the <code>printf()</code> function.</p>
####代码区块
和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块,通常这些区块我们并不希望它以一般段落文件的方式去排版,而是照原来的样子显示,Markdown有两种方式,最终都是用`<pre> `和 `<code>`标签来把代码区块包起来。一个代码区块会一直持续到没有缩进的那一行(或是文件结尾)。
例如:
这是一个普通段落:
这是一个代码区块。
Markdown 会转换成:
<p>这是一个普通段落:</p>
<pre><code>这是一个代码区块。
</code></pre>
两种方法:
* 4个空格的缩进或1个制表符
* 在代码段落的头部和尾部用三个间隔号包围起来(建议的方式,建议三个间隔号单占一行)
如果已经有制表符或空格,被认为是代码区块了,此时再打间隔符,也会输出间隔符。
在代码区段内,& 和尖括号都会被自动地转成 HTML 实体,这使得插入 HTML 原始码变得很容易,Markdown 会把下面这段:
Please don't use any `<blink>` tags.
转化为:
<p>Please don't use any <code><blink></code> tags.</p>
####代码区块高亮
代码块是Markdown内置语法之一,但是并不包含代码高亮。而highlight是Markdown常见插件之一,可实现目前大部分常见代码的高亮显示,大大提高代码可读性。想知道全部支持的语法名字参见 highlight.js demo page.
可在用 \`\`\` 包围的代码块头标明高亮的语法名字,参考下面例子:
```python
s = "Python syntax highlighting"
print s
```
```js
window.addEventListener('load', function() {
console.log('window loaded');
});
```
###图片
很明显地,要在纯文字应用中设计一个「自然」的语法来插入图片是有一定难度的。
Markdown 使用一种和链接很相似的语法来标记图片,同样也允许两种样式: 行内式和参考式。
####行内式
详细叙述如下:
* 一个惊叹号 !
* 接着一个方括号,里面放上图片的替代文字
* 接着一个普通括号,里面放上图片的网址,最后还可以用引号包住并加上 选择性的 'title' 文字。
比如:
![Alt text](/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional title")
####参考式
「id」是图片参考的名称,图片参考的定义方式则和连结参考一样:
![Alt text][id]
然后再在文件的其他地方写明:
[id]: url/to/image "Optional title attribute"
到目前为止, Markdown 还没有办法指定图片的宽高,需要的话,也可以使用普通的 `<img>` 标签。
如:
测试1:
此处是罗尼照片:![ronaldo][1]
[1]:1.jpg
测试2:
此处是罗尼照片:![ronaldo][]
[ronaldo]:2.jpg 、、、
测试3:
此处是罗尼照片:
<img src="2.jpg">
注:此例子中文件要与图片保存在同一个目录下。
###其它
####自动链接
Markdown 支持以比较简短的自动链接形式来处理网址和电子邮件信箱,只要是用尖括号包起来, Markdown 就会自动把它转成链接。一般网址的链接文字就和链接地址一样,例如:
<http://example.com/>
Markdown 会转为:
<a href="http://example.com/">http://example.com/</a>
####反斜杠Escape(character) 转义符
Markdown 可以利用反斜杠来插入一些在语法中有其它意义的符号,例如:如果你想要用星号加在文字旁边的方式来做出强调效果(但不用 `<em>` 标签),你可以在星号的前面加上反斜杠:
[TOC]
##宗旨
Markdown 是一种轻量级标记语言,能将文本换成有效的XHTML(或者HTML文档,它的目标是实现易读易写,成为一种适用于网络的书写语言。
**注意:上一行有没有空行,对md把md文件转为html很关键**
##兼容 HTML
Markdown 不是想要取代 HTML,甚至也没有要和它相近,它的语法种类很少,只对应 HTML 标记的一小部分。
Markdown 的理念是,能让文档更容易读、写和随意改。
HTML 是一种发布的格式,Markdown 是一种书写的格式。就这样,Markdown的格式语法只涵盖纯文本可以涵盖的范围。
不在 Markdown 涵盖范围之内的标签,都可以直接在文档里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown;只要直接加标签就可以了。
要制约的只有一些 HTML 区块元素――比如 ``` <div>、<table>、<pre>、<p> ```等标签,必须在前后加上空行与其它内容区隔开,还要求它们的开始标签与结尾标签不能用制表符或空格来缩进。Markdown 的生成器有足够智能,不会在 HTML 区块标签外加上不必要的 ```<p>``` 标签。
例子如下,在 Markdown 文件里加上一段 HTML 表格:
这是一个普通段落。
```
<table>
<tr>
<td>Foo</td>
</tr>
</table>
```
这是另一个普通段落。
请注意,在 HTML 区块标签间的 Markdown 格式语法将不会被处理。比如,你在 HTML 区块内使用 Markdown 样式的*强调*会没有效果。
HTML 的区段(行内)标签如 `<span>、<cite>、<del>` 可以在 Markdown 的段落、列表或是标题里随意使用。依照个人习惯,甚至可以不用 Markdown 格式,而直接采用 HTML 标签来格式化。举例说明:如果比较喜欢 HTML 的 `<a>或 <img> `标签,可以直接使用这些标签,而不用 Markdown 提供的链接或是图像标签语法。
和处在 HTML 区块标签间不同,Markdown 语法在 HTML 区段标签间是有效的。
##特殊字符自动转换
markdown会对Html里的两个字符进行转换,是< 和 & ,要额外注意一下。
##区块元素
###段落和换行
1.建议在每个段落的前后加上一行以上的空行
2.在md文件中的一个回车换行,不等于在对应的html中加入了`<br/>`,这点要注意,如果需要强制换行,要打两个及以上的空格,一个回车;或者使用`</br>标签`
###标题
支持两种标题语法:类Setext和atx形式
```
Setext:
This is an H1
=============
This is an H2
-------------
atx:插入1-6个#,如果为了美观,后面也可以插入对应个数的#
# 这是 H1
## 这是 H2
###### 这是 H6
```
###区块引用 Blockquotes (左侧有一个竖线)
Markdown 标记区块引用是使用类似 email 中用 > 的引用方式。如果你还熟悉在 email 信件中的引言部分,你就知道怎么在 Markdown 文件中建立一个区块引用,那会看起来像是你自己先断好行,然后在每行的最前面加上 >
例如:
```
> ## 这是一个标题。
>
> 1. 这是第一行列表项。
> 2. 这是第二行列表项。
>
> 给出一些例子代码:
>
> return shell_exec("echo $input | $markdown_script");
```
###列表
1.无序列表:使用星号*、加号+或是减号-作为列表标记。要注意的是:
* 标记号右边必须有空格,且标记号左侧的空格不能超过3个空格,否则会认为是代码区块。
* 如果上一行不是空行,也不会被认为是代码区块,因为按md标准,需要有空行,同时,也不会被认为是标记,因为按md标准,也是需要空行的
* 记得在第一个标记的上一行,要输入两个空格加一个回车
2.有序列表:使用数字接着一个英文句点做为开发。要注意的是:
* 标记号右边必须有空格,且标记号左侧的空格不能超过3个空格,否则会认为是代码区块。
* 如果上一行不是空行,也不会被认为是代码区块,因为按md标准,需要有空行,同时,也不会被认为是标记,因为按md标准,也是需要空行的
* 记得在第一个标记的上一行,要输入两个空格加一个回车
* 即使在md文件中,序号是错的,在html中也会自动修改为正确的
* 如果碰到 1990.1.1这种被误转成列表了,可以在句点之前加上反斜线。`1986\.`
列表中:如果想在列表内部加入引用,则 > 就需要缩进,如果要放代码区块的话,该区块就需要缩进两次,也就是 8 个空格或是 2 个制表符
###代码区块
和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块,通常这些区块我们并不希望它以一般段落文件的方式去排版,而是照原来的样子显示,Markdown 会用 `<pre> `和 `<code>`标签来把代码区块包起来。
要在 Markdown 中建立代码区块很简单,只要简单地缩进 4 个空格或是 1 个制表符就可以
这个每行一阶的缩进(4 个空格或是 1 个制表符),都会被移除。一个代码区块会一直持续到没有缩进的那一行(或是文件结尾)。
例如:
这是一个普通段落:
这是一个代码区块。
Markdown 会转换成:
<p>这是一个普通段落:</p>
<pre><code>这是一个代码区块。
</code></pre>
如果已经有制表符或空格,被认为是代码区块了,此时再打间隔符,也会输出间隔符。
###分隔线
可以在一行中用三个以上的星号、减号、底线来建立一个分隔线,行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线。(上一行不需要为空,比如下面的示例就可生效)
- - -
* * *
___
###链接
Markdown 支持两种形式的链接语法: 行内式和参考式两种形式。
不管是哪一种,链接文字都是用 [方括号] 来标记。
####行内式
要建立一个行内式的链接,只要在方块括号后面紧接着圆括号并插入网址链接即可,如果你还想要加上链接的 title 文字,只要在网址后面,用双引号把 title 文字包起来即可,例如:
This is [an example](http://example.com/ "Title") inline link.
[This link](http://example.net/) has no title attribute.
如果你是要链接到同样主机的资源,你可以使用相对路径:
See my [About](/about/) page for details.
####参考式
参考式的链接是在链接文字的括号后面再接上另一个方括号,而在第二个方括号里面要填入用以辨识链接的标记。
链接内容定义的形式为:
* 方括号(前面可以选择性地加上至多三个空格来缩进),里面输入链接文字
链接辨别标签可以有字母、数字、空白和标点符号,但是并不区分大小写,因此下面两个链接是一样的:
* 接着一个冒号
* 接着一个以上的空格或制表符
* 接着链接的网址
* 选择性地接着 title 内容,可以用单引号、双引号或是括弧包着
例如:
[foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ 'Optional Title Here'
有一个已知的问题是 Markdown.pl 1.0.1 会忽略单引号包起来的链接 title。
[foo]: http://example.com/ (Optional Title Here)
[id]: <http://example.com/> "Optional Title Here"
以上四种情况相同
隐式链接标记功能让你可以省略指定链接标记,这种情形下,链接标记会视为等同于链接文字,要用隐式链接标记只要在链接文字后面加上一个空的方括号。
如可以将:
I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"
改写为
I get 10 times more traffic from [Google][] than from
Yahoo][] or [MSN][].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"
其中,方括号里面的链接辨别标签里,可以加上空格。
###强调(斜体及粗体)
Markdown 使用星号(*)和底线(_)作为标记强调字词的符号,被 * 或 _ 包围的字词会被转成用 `<em>` 标签包围,用两个 * 或 _ 包起来的话,则会被转成 `<strong>`,例如:
*single asterisks*
_single underscores_
**double asterisks**
__double underscores__
会转成:
<em>single asterisks</em>
<em>single underscores</em>
<strong>double asterisks</strong>
<strong>double underscores</strong>
强调也可以直接插在文字中间,但是如果 * 和 _ 两边都有空白的话,它们就只会被当成普通的符号。
如果要在文字前后直接插入普通的星号或底线,可以用反斜线,如:
\*this text is surrounded by literal asterisks\*
###代码区块及高亮
####行内代码块
在行内,某些字符是代码块的话,用一个间隔符来标记,它会自动转为`<code>`标签来标记,即键盘上1左边的那个键(英文状态下)
例如:
Use the `printf()` function.
会产生:
<p>Use the <code>printf()</code> function.</p>
####代码区块
和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块,通常这些区块我们并不希望它以一般段落文件的方式去排版,而是照原来的样子显示,Markdown有两种方式,最终都是用`<pre> `和 `<code>`标签来把代码区块包起来。一个代码区块会一直持续到没有缩进的那一行(或是文件结尾)。
例如:
这是一个普通段落:
这是一个代码区块。
Markdown 会转换成:
<p>这是一个普通段落:</p>
<pre><code>这是一个代码区块。
</code></pre>
两种方法:
* 4个空格的缩进或1个制表符
* 在代码段落的头部和尾部用三个间隔号包围起来(建议的方式,建议三个间隔号单占一行)
如果已经有制表符或空格,被认为是代码区块了,此时再打间隔符,也会输出间隔符。
在代码区段内,& 和尖括号都会被自动地转成 HTML 实体,这使得插入 HTML 原始码变得很容易,Markdown 会把下面这段:
Please don't use any `<blink>` tags.
转化为:
<p>Please don't use any <code><blink></code> tags.</p>
####代码区块高亮
代码块是Markdown内置语法之一,但是并不包含代码高亮。而highlight是Markdown常见插件之一,可实现目前大部分常见代码的高亮显示,大大提高代码可读性。想知道全部支持的语法名字参见 highlight.js demo page.
可在用 \`\`\` 包围的代码块头标明高亮的语法名字,参考下面例子:
```python
s = "Python syntax highlighting"
print s
```
```js
window.addEventListener('load', function() {
console.log('window loaded');
});
```
###图片
很明显地,要在纯文字应用中设计一个「自然」的语法来插入图片是有一定难度的。
Markdown 使用一种和链接很相似的语法来标记图片,同样也允许两种样式: 行内式和参考式。
####行内式
详细叙述如下:
* 一个惊叹号 !
* 接着一个方括号,里面放上图片的替代文字
* 接着一个普通括号,里面放上图片的网址,最后还可以用引号包住并加上 选择性的 'title' 文字。
比如:
![Alt text](/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional title")
####参考式
「id」是图片参考的名称,图片参考的定义方式则和连结参考一样:
![Alt text][id]
然后再在文件的其他地方写明:
[id]: url/to/image "Optional title attribute"
到目前为止, Markdown 还没有办法指定图片的宽高,需要的话,也可以使用普通的 `<img>` 标签。
如:
测试1:
此处是罗尼照片:![ronaldo][1]
[1]:1.jpg
测试2:
此处是罗尼照片:![ronaldo][]
[ronaldo]:2.jpg 、、、
测试3:
此处是罗尼照片:
<img src="2.jpg">
注:此例子中文件要与图片保存在同一个目录下。
###其它
####自动链接
Markdown 支持以比较简短的自动链接形式来处理网址和电子邮件信箱,只要是用尖括号包起来, Markdown 就会自动把它转成链接。一般网址的链接文字就和链接地址一样,例如:
<http://example.com/>
Markdown 会转为:
<a href="http://example.com/">http://example.com/</a>
####反斜杠Escape(character) 转义符
Markdown 可以利用反斜杠来插入一些在语法中有其它意义的符号,例如:如果你想要用星号加在文字旁边的方式来做出强调效果(但不用 `<em>` 标签),你可以在星号的前面加上反斜杠: