Markdown Syntax

Posted on   |   In   |  

本文译于Markdown英文文档

综述:

哲学

Markdown的目的是实现易读易写．

易读是最重要的．Markdown格式的文件应该像纯文本那样按照原样发表，而不是看起来像使用标签或格式化的指令进行了标记．虽然Markdown的语法受到了现有的几个text-to-HTML格式的影响，包括Setext, atx, Textile, reStructuredText, Grutatext, and EtText, 但是最大的灵感来自于纯文本格式的邮件．

为了这个目的，Markdown的语法完全由标点字符组成，选取的标点字符最大程度的表达出它所表示的意思．举例来说．星号围绕着一个单词看起来像*强调*．Markdown列表看起来，就是列表．即使是块引用看起来也像引用的文本的样子，假设你曾经使用过email．

内嵌HTML

Markdown的语法只为一个目的：作为一种网络的写作格式．

Markdown并不是要替代HTML或者和它相似．它的语法很少，只是和HTML标签的一个很小的子集相对应．这个观念并不是创建一个更易于嵌入HTML标签的语法．我认为HTML标签已经是很容易插入的了．Markdown的目的就是让它更易于读，写，编辑文章．HTML是一种发布格式；Markdown是一种写作格式．因此，Markdown的格式语法只是解决那些和纯文本有关的问题．

对于Markdown的语法没有覆盖到的问题，你可以使用HTML．没必要表明你从Markdown转换到了HTML；你只是使用标签而已．

唯一的限制时块级的HTML元素必须使用空行分开周围的内容，块的开始和结束的标签不能使用Tab或空格缩进，例如：<div>, <table>, <pre>,<p>等等．Markdown非常聪明，并不会围绕HTML的块级标签添加额外（不需要）的<p>标签．

例如，添加一个HTML的table到Markdown文中：

This is a regular paragraph.

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

This is another regular paragraph.

注意：Markdown的格式语法并不能在块级别的HTML标签中被处理．

例如：你不能使用Markdown风格的*emphasis*在HTML块中．

HTML的区段标签可以使用在Markdown的段落，列表，标题中．例如：<span>, <cite>, <del>．你也可以使用HTML标签代替Markdown格式化；例如：如果你喜欢，你可以使用<a>或者<img>标签代替Markdown的链接或图片语法．

和块级的HTML标签不同的是，Markdown语法是在span级的标签中处理的．

特殊字符的自动转换

在HTML中，＇<＇和＇&＇这两个字符需要特殊处理．＇<＇用于标签的开始；＇&＇用于表示HTML实体．如果你想把它们当做普通字符使用，需要转换为＇<＇和＇&＇.

尤其是＇&＇让网络文档写者头疼．如果你想写＇AT&T＇，你需要写成＇AT&T＇．甚至在URL中的＇&＇符号也需要进行转换．因此，如果你想链接到：

http://images.google.com/images?num=30&q=larry+bird

你需要在你的链接属性href中把URL该写成：

http://images.google.com/images?num=30&amp;q=larry+bird

不用说，这很容易忘记，并且可能是在其他网站的验证性错误中最常见的．

Markdown自然允许你使用这些符号，并且为你考虑到了所有必要的转换．如果你在HTML实体中使用了＇&＇，它保持不变；否则它将转换成＇&＇．

因此，如果你想在你得文章中包含版权标记，你可以写成：

&copy;

并且Markdown不会管它．但是如果你写成：

AT&T

Markdown将把它转换成：

AT&amp;T

同样的，因为Markdown支持内嵌HTML，如果你使用＇<＇作为HTML标签的分隔符，Markdown将会想这样对待它们．但是如果你写成：

4 < 5

Markdown将会把它转换成：

4 &lt; 5

然而，在Markdown的code spans and blocks中，＇<＇和＇&＇总是自动转换．这样使用Markdown来写HTML代码会很简单．（不同于原始的HTML,HTML语法的格式太可怕了，因为每一个＇<＇和＇&＇在你的代码示例中都要被转换．）

块元素

段落和行分隔符

段落就是一个或多个连续的文本行，由一个或多个空行分隔．（空行就是任何看起来只包含空格或Tab的行．）普通的段落不应该使用空格或Tab缩进．

＂一个或多个连续的文本行＂规则的含义是Markdown支持”hard-wrapped”文本段．这和大部分其他的text-to-HTML格式化程序（包括Movable Type的＂转换为换行符＂选项）有很大不同，这些格式化程序将每个段落中的换行字符转换成<br />标签．

当你想要使用Markdown插入一个<br />标签时，你要使用两个或更多的空格结束这一行，然后输入return．

是的，这需要更大的努力来产生一个<br />，但是一个过分简单化的”每一个换行符是一个<br />”规则对Markdown不起作用．当你使用hard breaks来格式化它们时,Markdown的email风格的块引用和多段落列表条目做的更好，看起来也更好.

标题

Markdown支持两种类型的标题，Setext和atx．

Setext类型的标题是”underlined”，使用等号（对于一级标题）和破折号（对于二级标题）．例如：

This is an H1
=============
This is an H2
-------------

效果如下：

任何数量下划的＇=＇或＇-＇都可以

Atx类型的标题在行开始位置使用1-6个＇#＇字符，对应标题等级的1-6．例如：

# This is an H1

## This is an H2

###### This is an H6

效果如下：

你可以随意的使用＂闭合＂的atx类型的标题．这只是装饰用的，如果你认为它看起来更美观，你可以使用．标题前后的＇#＇符号的个数可以不同．（标题前面的＇#＇的个数决定了标题的等级）：

# This is an H1 #

## This is an H2 ##

### This is an H3 ###

效果如下：

块引用

对于块引用，Markdown使用email风格的＇>＇字符来实现．如果你熟悉在email消息中引用文章的段落，那么你就知道怎么在Markdown中创建一个块引用．如果你hard wrap文本并且在每行之前加入＇>＇符号，那看上去会很不错．

> 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 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.

效果如下：

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 is some example code;
>
>    return shell_exec("echo &input | &markdown_script");

效果如下：

任何体面的文本编辑器都应该使email风格的引用简单化．例如：BBEdit，你可以从文本菜单中进行选择或者增加引用级．

列表

Markdown支持有序的（数字的）和无序的（分项的）列表．

无需列表使用　＇*＇,　＇+＇,　＇-＇ 作为列表标记：

* Red
* Green
* Blue

使用 ＇+＇ 和 ＇-＇ 是等效的：

- Red
- Green
- Blue

效果是：

  • Red
  • Green
  • Blue

有序列表使用数字后面紧跟着英文句点：

1. Bird
2. McHale
3. Parish

效果是：

  1. Bird
  2. McHale
  3. Parish

注意：你用来进行标记的数字对于Markdown产生的HTML结果的输出并没有影响．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

结果都一样：

  1. Bird
  2. McHale
  3. Parish

实际上，你将会得到相同的HTML输出．问题在于，如果你想的话，你可以在你的顺序列表里使用有序数，这样的话，在你的源码里的数字会和你发布的HTML中的数字相匹配．但是如果你想偷懒的话，大可不必如此．

然而如果你懒于进行列表编号，你仍然应该让列表从1开始．在将来的某个时候，Markdown可能会支持以任意数字开始的有序列表．

典型的列表编号从最左边开始，但可能会被最多三个空格缩进．列表标记后面必须跟着至少一个空格或Tab键．

为了让列表看起来更美观，你可以进行悬挂式缩进：

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

如果你想偷懒的话，大可不必如此：

*   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>标签在HTML的输出中包装条目．例如，这个输入：

*    Bird
*    Magic

将会变为：

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

但是这个：

*    Bird

*    Magic

将会变为：

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

列表条目可能由多个段落组成．在一个列表条目中的每一个后续段落必须使用4个空格或一个Tab键进行缩进．

1.  This is a list item 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.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

如果对于后续段落的每行进行缩进，看起来会更美，当然了，Markdown也允许你偷懒：

*    This is a list item with two paragraphs.

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

*    Another item in the same list.

效果是：

  • This is a list item with two paragraphs.

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

  • Another item in the same list.

把块引用放入列表条目中，块引用的＇>＇分隔符需要进行缩进：

* A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

把一个代码块放到列表里，代码块需要被缩进两次，也就是8个空格或者两个Tab:

*   A list item with a code block:

    <code goes here>

值的注意的是，你有可能无意中使用了有序列表，比如想这样：

1986. What a great season.

效果如下：

1. What a great season.

换句话说，在行首出现数字－句点－空白序列．为了避免这种情况，你可以使用反斜杠标识句点为普通字符：

1986\. What a great season.

代码块

提前格式化的代码块是用来编程或者标记源代码的．代码块的行是按照原样显示，而不是形成普通的段．Markdown会使用<pre>和<code>标签将一块代码包起来．

在Markdown中使用代码块，只需要在块的每行进行缩进至少4个空格或1个Tab键．例如：

This is a normal paragraph:
   This is a code block.

效果如下：

This is a normal paragraph:
#include <stdio.h>

int main()
{
return 0;
}

Markdown将会产生：

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

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

代码块每行的缩进（4个空格或1个Tab）被删除了．

例如：

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

将会返回：

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

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

当代码块遇到一个没有缩进的行（或者文章结尾）时就停止．

在一个代码块中，＇&＇和＇<＇, ＇>＇会被自动的转换为HTML实体．这会让用Markdown来包含HTML代码变的简单，只需要粘贴和缩进就行，Markdown会处理＇&＇, ＇<＇,＇>＇的麻烦编码．例如：

<div class="footer">
    &copy; 2004 Foo Corporation
</div>

将会转换为：

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

正常的Markdown语法并不会在代码中进行处理．例如：星号在代码块中就只是文字星号．这就意味着使用Markdown编写Markdown自己的语法也会很简单．

水平分隔线

你可以将至少三个＇-＇, ＇*＇或 ＇_＇单独放在一行中来产生水平分割吸纳标签（<hr />）．你也可以在放置＇-＇或＇*＇的行中使用空格．下面的没一行将会产生一个分隔线：

* * * 

***

******

- - -

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

跨度元素

链接

Markdown支持两种类型的链接：内联和引用．

在这两种类型中，链接文本由[方括号]分隔．

创建内联链接：紧跟着使用方括号包含的文本后面使用一组常规括号．在括号里放置你想要链接到的URL，对于链接还有一个可选的标题，都包含在括号里．例如：

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

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

效果是：

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

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

将会产生：

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

如果你引用了在同一台服务器上的资源，你可以使用相对路径：

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

效果是：

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

引用类型的链接：是使用第二组方括号，在里面放置你选择识别链接的标签：

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

你可以随意的使用空格来分隔这两组方括号：

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

因此，你需要在文章的某个地方(任何地方)使用单独一行来定义你的链接标签：

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

即：

  • 方括号中包含链接标识符（任意的使用最多三个空格从左边进行缩进）;
  • 紧跟着一个冒号；
  • 紧跟着一个或多个空格（或Tab）；
  • 紧跟着链接的URL；
  • 任意的跟着链接的标题属性．包含在单引号或双引号中，或者包含在圆括号中．

下面三种链接的定义表达的意义相同：

[foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ 'Optional Title Here'
[foo]: http://example.com/ (Optional Title Here)

注意：在Markdown.pl 1.0.1中有一个小错误，不能使用单引号来包含链接的标题．

链接的URL可以随意的被尖括号包含．

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

你可以把标题属性放到下一行，并用空格或Tab键来填充，这样当URL比较长时看起来会好些：

[id]: http://example.com/longish/path/to/resource/here
    "Optional Title Here"

链接的定义仅仅是在Markdown处理过程中创建链接，并且从你的HTML输出文件中被删去．

链接定义的名字可以由字母，数字，空格和标点符号组成，但是大小写是不敏感的．例如如下两个链接是相同的；

[link text][a]
[link text][A]

隐式链接的名字允许你忽略链接名，这样链接文本本身会成为链接名．只需要使用一对空的方括号就行，例如：链接”Google”到google.com，你可以这样写：

[Google][]

然后定义链接：

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

因为链接名可能包含空格，这样的简写对于链接文本是多个单词的情况时也适用：

Visit [Daring Fireball][] for more information.

然后定义链接：

[Daring Fireball]: http://daringfireball.net/

链接定义可以放在Markdown文中的任何位置．我认为应该直接把它们放在每个使用它们的段落的后面，你也可以把它们放在文章的最后面，有点像脚注．

几个还在工作着的引用链接：

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"

强调

Markdown使用＇*＇和＇_＇来表示强调．使用单个＇*＇或＇_＇包围的文字将会转换为被HTML标签<em>包围；使用两个＇*＇或＇_＇则转换为被HTML<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>

你可以使用你喜欢的风格；唯一的限制是，强调的开始和结尾处必须使用相同的符号．

强调可以用在一个词的中间：

un*frigging*believable

但是如果＇*＇或＇_＇两边都是空格的话，＇*＇或＇_＇将会被当做普通文本来对待．

如果在一个可能被当做强调符号的位置使用普通的＇*＇或＇_＇字符的话，你可以使用转义符：

\*this text is surrounded by literal asterisks\*

代码

为了显示一段代码，使用使用符号＇`＇（撇号）包围这段代码．不像预先处理好的代码块，一段代码可能是在一个段正常文本内．例如：

Use the `printf()` function.

效果是：

Use the printf() function.

将会产生：

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

为了可是在一个代码段中使用撇号，你可以在开始和结尾处使用多个撇号:

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

结果是：

There is a literal backtick (`) here.

将会产生：

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

包围一个代码段的撇号分隔符可以包含空格，一个在开始位置的后面，一个在结束位置的前面．这可以让你把作为文本的撇号放在代码段的开始或结束处：

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

一个代码段中的＇&＇和尖括号会自动的转换为HTML实体，这让包含HTML标签示例变的简单．Markdown将会返回：

Please don't use any `<blink>` tags.

效果是：

Please don’t use any <blink> tags.

到：

<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>

你可以这样写：

`&#8212;` is the decimal-encoded equivalent of `&mdash;`.

来产生：

<p><code>&amp;#8212;</code> is the decimal-encoded
equivalent of <code>&amp;mdash;</code>.</p>

图像

不可否认的，很难设计一个＂自然＂的语法来把图像放置到纯文本文件的格式中．

Markdown会像使用链接的语法那样使用图像语法，允许两种类型：内联和引用．

内联图像语法：

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

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

即：

  • 一个感叹号：!
  • 后面跟着一组方括号，为替换图像的文字
  • 后面跟着一对圆括号，包含图像的URL或者路径，然后是使用单引号或双引号包含的标题

引用风格的图像语法：

![Alt text][id]

“id”为定义的图像引用的名字．图像引用的定义使用的语法和链接引用相同．

[id]: url/to/image  "Optional title attribute"

在撰写文本时，Markdown没有语法指定图片的大小；如果这对你很重要，你可以使用规则的HTML<img>标签．

其他

自动链接

Markdown支持一种快捷方式的创建URL或email地址的＂自动＂链接：只使用尖括号包含URL或email地址．意思是如果你想显示URL或email地址的实际内容，以及是一个可点击的链接，你可以这样做：

<http://example.com/>

效果是：

http://example.com/

Markdown将会把它转换为：

<a href="http://example.com/">http://example.com/</a>

Email地址的自动链接和这个相似，除了Markdown会执行一点随机的十进制和十六进制的编码来帮助你掩盖地址，这是为了防止垃圾邮件．例如：

<address@example.com>

将会被转换为下面的代码:

<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允许你使用反斜杠转义，来使用那些在Markdown的格式化语法中有特殊意义的符号．例如，如果你想使用作为文本的星号（代替HTML的<em>标签）来包裹一个单词，你可以在星号前使用反斜杠，像这样：

\*literal asterisks\*

Markdown为下面的字符提供反斜杠转义：

\   反斜杠
`   撇号
*   星号
_   下划线
{}  花括号
[]  方括号
()  圆括号
#   井号
+   加号
-   减号（连字号）
.   点
!   感叹号

个人总结

对于这篇Markdown的语法说明，开始翻译时，看到网上已经有人翻译过了，就迟疑了，不知道是否有做的必要，将他们的译文和原文对照后，我感觉还是见仁见智，每个人对于原文的理解不同，表达自然不同．因此，我打算用自己的理解来完成这篇译文,耗时多天终于译完,这是我的第一篇完整的译文，能坚持译完还是很高兴的．由于译者能力有限，文中可能存在多出纰漏，希望大家多多指正．