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标签的开始，如果要直接显示'<'，必须写成 <
- '&' — 它用于标记html entity的开始，如果要直接显示'&'，必须写成 &
在MarkDown的语法中，你可以自然的使用'>'和'&'，MarkDown语法解析器会自动的判断你是否是在使用html标签，然后决定是否对这两个字符进行转义，但是在源代码区域(code block)，MarkDown语法解析器会始终对'<'和'&'转义
比如你写下
AT&T
a < b
MarkDown转化为html时会自动为
AT&T
a < 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个空格，第三级
将展示为
- item1, 数字前有0个空格，第一级
- item2, 数字前有1~4个空格，第二级
- item3
- item4
- item5
- 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">
© 2009 XXX Corporation
</div>
会转换为
<pre><code><div class="footer">
&copy; 2009 XXX Corporation
</div>
</code></pre>
代码片段中,普通的markdown语法将不再生效,比如abc就是字面含义,而不代表加粗显示. 这也意味着我们可以很方便的在markdown中嵌入markdown的代码片段.
水平分割线
3个以上的星号,减号,下划线单独在一行就会被转换为一个水平分割线(<hr />), 下面的写法都可以
***
* * *
*********
- - -
---------
_________
跨度元素
链接
markdown中支持两种链接方式: 内嵌(inline)和引用(reference)
在两种方式中, 链接文字都由方括号包含.
这是一个[包含标题(title)的内嵌链接](http://www.example.com/ "链接标题")的例子
这是一个没有标题(title)的内嵌链接的例子
会转换为
<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) - 引用方式2
目前在[Alexa排名][]前20位中的中国网站有: [百度][](6), [QQ][](10), [淘宝][](14), [新浪][](16)
以上三种方式都会生成如下的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>
由(`)包围的代码段中,& < > 都会被自动转义为 & < >
在html中`>`表示`>`符号
会转换为
<p>在html中<code>&gt;</code>表示<code>></code>符号</p>
图片
图片的表示和链接表示很相似, 同样有内嵌和引用两种表示方法
![Alt text][id]
[id]: http://example.com/test.jpg “可选的标题”
杂项
自动链接
用尖括号把链接和邮件地址包围起来时, markdown会自动的将它们转换为可点击的链接:
<http://example.com>
<[email protected]>
将会转换为
<a href="http://example.com">http://example.com</a>
<a href="mailto:addre
ss@example.co
m">address@exa
mple.com</a>
为了组织发送垃圾邮件的机器人爬虫, 邮件地址的转换稍微复杂一写. 但对于普通用户从浏览器中来看,它依然是一个可用点击指向"[email protected]"的邮件链接
反斜扛
对于markdown语法中有特殊含义的标点符号, 都可用在使用反斜杠转义以表达它们的字面含义, 可以被转义的字符包括
反斜杠
`
* 星号
_ 下划线
{} 大括号
[] 中括号
() 小括号
# 井号
+ 加号
- 减号
. 小数点
! 感叹号
Posted via UltraBlog.vim.
Last modified on 2011-06-20