Markdown标记语言上手笔记

Author : lovecicy

最近在玩Github,新建了一个测试项目,用来熟悉Github的操作,发现README文件的排版挺好玩的,就查看了下Github Flavored Markdown, 发现和之前在StackOverflow上使用的是同一种排版方式,通过简单方便的字符排列,就可以写出排版良好的页面。查了下,发现Markdown是苹果的狂热粉丝John Gruber创建的一种轻量级标记语言。在Daring Fireball上的介绍页上,给Markdown的定位是:a text-to-HTML conversion tool for web writers,是为web写手打造的文字转HTML工具。

通过几分钟的学习,你就可以很快上手,这也印证了Markdown的介绍,为web写手提供的简单易用的排版工具,你可以用易读易写的方式编辑文章,然后用它方便的转化成(X)HTML。

下面就来看一下Daring Fireball网站的文档,学习下Markdown的标准语法:

1. 行内元素

对于Markdown语法没有覆盖到的标签,你可以直接使用HTML而不用任何特殊的声明或语法来说明你正在Markdown和HTML之间切换。唯一的限制就是,对于块级HTML元素,HTML代码与Markdown文字部分必须有一行空行,并且开始与闭合标签必须顶格,就像下面一样:

This is a regular paragraph.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

This is another regular paragraph.

注意,在块级HTML代码里,将不会处理Markdown格式的语法,比如在块级元素里使用的Markdown格式“*emphasis*”将不会被处理成加粗格式,星号也只是正常的符号。

内联元素如<span>,<del>,<cite>等则可在任意的Markdown段落中使用,如果你愿意,你甚至可以直接使用HTML标签来代替Markdown格式。比如你可以使用<a>或者<img>标签来代替Markdown的链接或图像语法。

自动转换特殊符号

在Markdown中,你不必对 ‘<‘ 和 ‘&’ 符号做特殊处理(用&lt;表示 ‘<‘ ,用&amp;表示 ‘&’ ),Markdown会自动帮你处理。这样,当你想要写‘4<5’时,就不必担心是否要写成‘4&lt;5’了。

2. 块级元素

段落与换行

Markdown不会将回车转换成 ‘<br/>’ ,如果你真的要插入 ‘<br/>’ ,你需要在这一行末尾添加两个或以上的空格再回车。

标题

Markdown支持两种格式的标题语法。

第一种是用下标法,你可以在文字下一行添加 ‘=’ 来表示一级标题,在文字下一行添加 ‘-‘ 来表示二级标题。

This is an H1
=============

This is an H2
-------------

添加的下标数量没有限制,一个等号(=)或者连字符(-)都能生效。

第二种是使用多个井号(#)来表示各级标题,比如:

# This is an H1

## This is an H2

###### This is an H6

引用

Markdown使用 ‘>’ 来表示引用。

你可以在每行前面都添加 ‘>’ ,比如:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> 
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

Markdown也允许你偷懒,你也可以这样:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

引用还能嵌套,只需多加一个 ‘>’ 即可:

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

引用中还能包含其他Markdown格式的元素,比如标题,列表或代码段:

> ## This is a header.
> 
> 1.   This is the first list item.
> 2.   This is the second list item.
> 
> Here's some example code:
> 
>     return shell_exec("echo $input | $markdown_script");

列表

Markdown支持有序列表和无序列表。

无序列表使用星号(*), 加号(+)或连字符(-)来标记列表。比如:

*   Red
*   Green
*   Blue

等价于:

+   Red
+   Green
+   Blue

也等价于:

-   Red
-   Green
-   Blue

有序列表使用数字后面紧跟句号来标记:

1.  Bird
2.  McHale
3.  Parish

有趣的是,你使用的数字对列表的显示并没有影响,Markdown将上面的语句转换成一下的HTML代码:

<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>

即使你使用下面的Markdown语句:

1.  Bird
1.  McHale
1.  Parish

甚至这样的语句:

3. Bird
1. McHale
8. Parish

你得到的都是同样的HTML代码。

注意,列表标记后面至少跟一个或多个空格或者一个制表符。

单个列表项有多行的话,每行可以缩进也可以不缩进:

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.

如果你比较懒,你也可以这样:

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

如果列表项之间有换行,则Markdown会对列表项嵌套段落标签(<p/>),下面的Markdown列表:

*   Bird
*   Magic

将被转换成:

<ul>
<li>Bird</li>
<li>Magic</li>
</ul>

而如果这样:

*   Bird

*   Magic

则将被转换成这样的HTML段落:

<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>

列表项可能有多行,随后的每一段开头必须缩进4个的空格或一个Tab键。

*   This is a list item with two paragraphs.

    This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.

*   Another item in the same list.

要在列表中添加引用,则引用的符号 ‘> ‘ 也必须缩进缩进,就像下面这样:

 

如果要在列表中添加代码块,则代码块部分的内容必须缩进8个空格或2个Tab键。

*   A list item with a code block:

        <code goes here>

对于可能错误触发列表的情况,比如你想写这么一段文字:

1986. What a great season.

换句话说,对于以数字后面跟着句号开头的行,你必须在句号前面加反斜杠进行转义:

1986\. What a great season.

代码块

预格式化的代码块用来书写程序或标记语言源代码。要在Markdown中处理代码块,只需要简单的缩进4个空格或一个Tab键即可。比如:

This is a normal paragraph:

    This is a code block.

Markdown会生成如下的HTML:

<p>This is a normal paragraph:</p>

<pre><code>This is a code block.
</code></pre>

代码块的每一行都需要进行缩进,在显示时,每一行的4个空格或1个Tab键会被移除。比如下面这段Markdown文字:

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

会被转换成如下的HTML标记:

<p>Here is an example of AppleScript:</p>

<pre><code>tell application "Foo"
    beep
end tell
</code></pre>

碰到没有进行缩进的行或文章结束时,代码块就会结束。

在代码块中,&符号和尖括号(<,>)会自动被转成HTML实体。常规的Markdown语法在代码块中并不会生效,比如星号在代码块中只是一个字面量。

水平线

要产生一条水平线,只需要在单独的一行放置3个星号,连字符或下划线,在符号之间可以加空格。下面的格式都能生成一条水平线:

* * *

***

*****

- - -

---------------------------------------

3. 内联元素

链接

Markdown支持两种类型的链接格式:行内方式与引用方式。每种方式的链接文字都被包围在方括号之间。

要生成一个行内的链接,可以在方括号后面立即跟一对圆括号,圆括号内放的是链接的url地址,url地址后跟一个可选的用双引号包裹的链接标题,用空格隔开。比如下面的文字:

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

将生成如下HTML:

<p>This is <a href="http://example.com/" title="Title">
an example</a> inline link.</p>

<p><a href="http://example.net/">This link</a> has no
title attribute.</p>

如果你的链接是同一个server下的,则可以只用相对路径:

See my [About](/about/) page for details.   

引用方式的链接使用两对方括号,后一对方括号的内是链接url对应的id:

This is [an example][id] reference-style link.

然后在文档的任意地方,为链接的定义添加单独的一行:

[id]: http://example.com/  "Optional Title Here"

格式为:

1. 方括号内为链接的id,不区分大小写。

2. 方括号后紧跟着一个冒号。

3. 之后跟着一个或多个空格或Tab键。

4. url地址,可用尖括号包裹。

5. 可选的链接标题,用双引号,单引号或括号包裹。

在引用的地方,第二对方括号如果为空,则id与链接文字相同。引用方式的链接的意义在于增强文档可读性。

强调

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\*

代码

要使用行内代码,需要使用重音符引号(键盘1键左边的按键)包裹。

Use the `printf()` function.

将被转换成:

<p>Use the <code>printf()</code> function.</p>

要在行内代码中使用重音符引号,可以使用多个重音符引号来包裹行内代码文字:

``There is a literal backtick (`) here.``

将会转换成:

<p><code>There is a literal backtick (`) here.</code></p>

图片

与链接相类似,图片也有两种表示方式;同样,形式也相同,只不过在链接的格式前加一个感叹号(!)。

行内的图片链接:

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

引用方式的图片链接:

![Alt text][id]

如果你愿意,你还可以直接使用'<img>’ 标签。

虽然说要看完这么多语法规定需要一定的时间,但是聪明的你肯定学一遍就会了,这可是在程序猿界越来越流行的标记语言哦,相信你能轻松掌握的。

要查看更多关于Markdown的文档,请参阅:Daring Fireball

同时,Github Flavored Markdown与标准的Markdown还是有些出入的,加入了一个更方便的东西,比如对代码块的语法增加了3个重音符包裹的语法,并指名代码的语言,Github会自动对代码进行语法高亮,要查看更多详情,请参阅:Github Flavored Markdown

standard

Have your say