software / 笔记 · 2013 年 3 月 30 日 0

Markdown标记语言上手笔记

最近在玩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

标签：

您可能还喜欢...

发表评论

您的电子邮箱地址不会被公开。 必填项已用*标注