MarkDown语法

github的各个项目里面一般都会有个readme.mk, 它能自动转换为项目的说明页面. 这个文件使用的是MarkDown语法.
最近装了UltraBlog.vim插件, 它也可以使用MarkDown来写博客, 于是就专门学习了一下MarkDown的语法, 以下就是对 MarkDown Syntax的一些摘要


概览

MarkDown让你用纯文本的方式写作,而且可以很轻松的转换成对应的HTML

嵌入html

MarkDown里可以直接嵌入html, 有两点需要注意

  • 对于block-level的html标签(<div><table><pre><p> ...),使用时整个html文本块必须和前后的普通文本用空行隔开,并且开始和结束部分的html标签不能有缩进。MarkDown语法解析时将不处理嵌入的html文本块,也就是说,在嵌入的html块中无法使用markdown的语法,必须使用原生的html
  • 对于span-level的html标签(<span><a><img>...),可以直接在使用,不必独立成行,而且在这些html标签包含的区域内的内容,MarkDown语法解析器仍然会起作用,可以使用MarkDown语法

特殊转义

HTML中需要特殊转义的字符

  • '<' — 它用于标记html标签的开始,如果要直接显示'<',必须写成 &lt;
  • '&' — 它用于标记html entity的开始,如果要直接显示'&',必须写成 &amp;

在MarkDown的语法中,你可以自然的使用'>'和'&',MarkDown语法解析器会自动的判断你是否是在使用html标签,然后决定是否对这两个字符进行转义,但是在源代码区域(code block),MarkDown语法解析器会始终对'<'和'&'转义

比如你写下

AT&T
a < b

MarkDown转化为html时会自动为

AT&amp;T
a &lt; b

块元素

段落

  • 连续的行被当作一个段落,段落之间用空行分隔。
  • 所谓空行,只要是看起来是空行就行,也就是说空行里可以有空格和制表符,而不需要在行首就是换行符
  • 普通段落的文本不能有缩进
  • 如果段落中想换行(插入<br>标签),只需要在相应行文本的最后有两个或以上的空格就行

MarkDown支持两种写标题的方式:

第一种:

一级标题
======

二级标题
------

任意数量的'='和'-'都可以

第二种:

# 一级标题

## 二级标题

### 三级标题 ###

'#'的个数代表了标题的级别,尾部的#不是必须的

引用

MarkDown里面以'>'开头的行将会认为是一个引用区域(blockquote),如果你经常上BBS或者收发邮件,你应该很熟悉这种语法:

> 这是一个
> 引用区域

将会显示为:

这是一个
引用区域

引用区域每行前面都可以写一个'>',这样会好看一点,但是你也可以偷懒,只在整个段落的第一行前面加一个'>',这样同样会把整个段落当作一个引用区域。
所以上面的代码也可以写为

> 这是一个
引用区域

引用区域内部可以继续使用MarkDown语法,这也意味着引用可以嵌套,只要在行首多写一个'>'字符就可以了。比如

> 这是一个
> 引用区域
>> 这是第二个
>> 引用区域
> ## 标题
>
> 代码:
>
>     die(json_encode($ret));

会展示为

这是一个
引用区域

这是第二个
引用区域

标题

代码:

die(json_encode($ret));

列表

无序列表可以有三种写法

* item1
* item2
* item3

+ item1
+ item2
+ item3

- item1
- item2
- item3

有序列表

1. item1
1. item2
1. item3

实际上,有序列表前面的数字可以是任意的,比如你也可以写为

3. item1
1. item2
8. item3

但是,在MarkDown的后续版本中,有序列表前的数字可能表示列表起始的编号,所以,你现在最好都使用数字1开头。

列表的开始符号 * + - 1 出现在每行的最左边,符号之后必须跟一个或多个空格

每4个空格的缩进为一级,下面的写法

1. item1, 数字前有0个空格,第一级
 2. item2, 数字前有1~4个空格,第二级
  3. item3
   4. item4
    5. item5
     6. item6, 数字前有5个空格,第三级

将展示为

  1. item1, 数字前有0个空格,第一级
    1. item2, 数字前有1~4个空格,第二级
    2. item3
    3. item4
    4. item5
      1. item6, 数字前有5个空格,第三级

每个列表元素里面是可以分段落的,每个子段落使用空行分隔,段落前面的缩进级别要相同

*   这是一个列表元素,段落1

    这是列表元素的第二个段落
依旧是第二个段落

* 这是另一个列表元素

会展示为

  • 这是一个列表元素,段落1

    这是列表元素的第二个段落
    依旧是第二个段落

  • 这是另一个列表元素

列表元素里面可以有引用和代码,标识引用的>符号前面需要有4个空格,而代码段的缩进需要是平常的两倍(8个空格)

  • 这是一个包含引用的列表元素

    hello, world!

  • 这是一个包含代码的列表元素
    System.out.println("hello, world!");
    

一个数字加.开头的行将会转化为有序列表,可是如果你就是想写下面这一行,而不转化为列表

1986. What a great season.

你可以写成这样:

1986. What a great season.

代码片段

在markdown中,缩进4个空格以上的区域就会转化为一个代码片段,比如

这是一个普通的段落

    这是一个代码片段
    echo "hello, world!"

将会转化成如下的html片段

<p>这是一个普通的段落</p>

<pre><code>这是一个代码片段
echo "hello, world!"</pre></code>

代码片段转换成html时,会自动的移除一级缩进(4个空格或者一个tab). 比如下面的

    if test "$#" -ne 3
    then
        print_usage
    fi

会转化为

<pre><code>if test "$#" -ne 3
then
    print_usage
fi
</pre></code>

代码片段中的& < > 字符会被自动转义,所以在markdown中书写html源代码非常简单,只要把源代码复制进来,然后整体向右缩进4个空格就可以了.

<div class="footer">
    &copy; 2009 XXX Corporation
</div>

会转换为

<pre><code>&lt;div class="footer"&gt;
    &amp;copy; 2009 XXX Corporation
&lt;/div&gt;
</code></pre>

代码片段中,普通的markdown语法将不再生效,比如abc就是字面含义,而不代表加粗显示. 这也意味着我们可以很方便的在markdown中嵌入markdown的代码片段.

水平分割线

3个以上的星号,减号,下划线单独在一行就会被转换为一个水平分割线(<hr />), 下面的写法都可以

***
* * *
*********
- - -
---------
_________

跨度元素

markdown中支持两种链接方式: 内嵌(inline)和引用(reference)
在两种方式中, 链接文字都由方括号包含.

这是一个[包含标题(title)的内嵌链接](http://www.example.com/ "链接标题")的例子

这是一个[没有标题(title)的内嵌链接](http://www.example.com/)的例子

会转换为

<p>这是一个<a href="http://www.example.com/" title="链接标题">包含标题(title)的内嵌链接</a>的例子</p> 

<p>这是一个<a href="http://www.example.com/">没有标题(title)的内嵌链接</a>的例子</p>

链接地址可以是相对路径,比如:

您可以在[此页面](/about-me/)查看更多关于我的信息

引用类型的链接, 有连续的两个方括号包含的部分构成. 第一个方括号里是链接文字, 第二个方括号里是链接的标签

这是一个[引用链接][id]的例子

你可用在文档的任意位置定义链接标签, 以下几种方式是等价的:

[id]: http://www.example.com/ "可选的链接标题"
[id]: http://www.example.com/ '可选的链接标题'
[id]: <http://www.example.com/> (可选的链接标题)
[id]: <http://www.example.com/>
    "可选的链接标题"

定义链接标题属性时, 标题可以用单引号,双引号或者小括号包含, 链接地址也可以使用尖括号包含

链接标签名称里面可以有字母, 数字, 空格, 标点符号. 而且名称不区分大小写.

当链接文字和链接标签相同时,你可以不写链接标签, 比如

內事不决问老婆,外事不决问[google][]

然后,再定义google的链接:

[google]: http://www.google.com/

几种格式的对比:

  • 内嵌方式
    目前在[Alexa排名](http://www.alexa.com/topsites)前20位中的中国网站有:
    [百度]( http://baidu.com/)(6), [QQ](http://qq.com/)(10), [淘宝](http://taobao.com/)(14), [新浪](http://sina.com.cn/)(16)
    
  • 引用方式
    目前在[Alexa排名][alexa]前20位中的中国网站有:
    [百度][baidu](6), [QQ][qq](10), [淘宝][taobao](14), [新浪][sina](16)
    
    [alexa]: http://www.alexa.com/topsites "Alexa Top Sites"
    [baidu]: http://baidu.com/
    [qq]: http://qq.com/
    [taobao]: http://taobao.com/
    [sina]: http://sina.com.cn/
    
  • 引用方式2
    目前在[Alexa排名][]前20位中的中国网站有:
    [百度][](6), [QQ][](10), [淘宝][](14), [新浪][](16)
    
    [alexa排名]: http://www.alexa.com/topsites "Alexa Top Sites"
    [百度]: http://baidu.com/
    [QQ]: http://qq.com/
    [淘宝]: http://taobao.com/
    [新浪]: http://sina.com.cn/
    

以上三种方式都会生成如下的html代码

<p>目前在<a href="http://www.alexa.com/topsites">Alexa排名</a>前20位中的中国网站有:
<a href="http://baidu.com/">百度</a>(6),
<a href="http://qq.com/">QQ</a>(10),
<a href="http://taobao.com/">淘宝</a>(14),
<a href="http://sina.com.cn/">新浪</a>(16)</p>

重点强调

markdown中,星号(*)和下划线(_)用来标记重点文字

单个星号(*)或者下划线(_)包围的文字会在转换后包上HTML标签<em>

两个星号(*)或者下划线(_)包围的文字会在转换后包上HTML标签<strong>

如果 * 和 _ 两边都是空格,那么语法解析时会把它们当字面文字对待,不做转换. 或者也可以用反斜杠进行转义

*加粗方式1*
_加粗方式1_
**加粗方式2**
__加粗方式2__
这是一个 * 星号
这是一个_下划线

代码

在普通的段落中嵌入代码,需要使用(`)字符将代码包含起来:

使用`printf()`函数

将会转换为

<p>使用<code>printf()</code>函数</p>

如果代码片段中恰好有(`)字符,那么可以在前后各用两个``

`` result=`cat $logfile` ``

会转换为

<p><code>result=`cat $logfile`</code></p>

由(`)包围的代码段中,& < > 都会被自动转义为 &amp; &lt; &gt;

在html中`&gt;`表示`>`符号

会转换为

<p>在html中<code>&amp;gt;</code>表示<code>&gt;</code>符号</p>

图片

图片的表示和链接表示很相似, 同样有内嵌和引用两种表示方法

![Alt text](http://example.com/test.jpg "可选的标题")

![Alt text][id]
[id]: http://example.com/test.jpg "可选的标题"

杂项

用尖括号把链接和邮件地址包围起来时, markdown会自动的将它们转换为可点击的链接:

<http://example.com>
<address@example.com>

将会转换为

<a href="http://example.com">http://example.com</a>
<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;
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

为了组织发送垃圾邮件的机器人爬虫, 邮件地址的转换稍微复杂一写. 但对于普通用户从浏览器中来看,它依然是一个可用点击指向"address@example.com"的邮件链接

反斜扛

对于markdown语法中有特殊含义的标点符号, 都可用在使用反斜杠转义以表达它们的字面含义, 可以被转义的字符包括

 反斜杠
`
* 星号
_ 下划线
{} 大括号
[] 中括号
() 小括号
# 井号
+ 加号
- 减号
. 小数点
! 感叹号

Posted via UltraBlog.vim.

Comments