Markdown官方文档[翻译]

时间：2021-12-15 18:00:41

概述

哲学

Markdown目标是实现”易读易写”.

Markdown最大的亮点在于它的可读性。一篇Markdown格式的文档可以直接以纯文档的形式发布，并且它看起来并不会由标签和格式化指令构成。尽管Markdown语法受到一些已有的text-to-html格式转换工具的影响，包括Setext, atx, Textile, reStructuredText, Grutatext, 以及EtText。Markdown最大的灵感还是来自于纯文本格式的电子邮件格式。

为此，Markdown语法完全有标点符号组成，并且标点符号经过精心选择使得其看起来和需要表达的意思尽可能的相符。例如，用星号包裹一个单词，像这样:*emphasis*。Markdown的清单看起来，就跟清单表现样式很像。如果你还使用过电子邮件，区块引言(blockquotes)，看起来就真的像引用一段文字。

行内HTML

Markdown的语法只有一个目的:就是以一种固定的格式在网络上书写。
Markdown并不是为了替代HTML，甚至也没有必要和它相似。它的语法非常简单，只能和部分HTML标签相匹配。Markdown的思想并不是为了创建一种简单书写HTML标签的语法。在我看来，HTML标签已经非常容易书写了。Markdown是为了更容易阅读、书写以及编辑文章。HTML是一种发布的格式，Markdown是一种书写的格式。因此Markdown的语法知识为了专注于解决如果用纯文本的形式进行书写表达。

对于那些无法用Markdown语法进行表达的HTML标签，你只需要简单的使用HTML进行撰写即可。不需要额外标注这是HTML或是Markdown，只需要直接加标签即可。

唯一的限制是HTML的块级元素，比如<div>,<table>,<pre>,&ltp>等等，必须用空行将其与上下文内容隔开，并且开始和结束标签不能用tab和空格来缩进排版。Markdown足够聪明，不会在块级元素周围添加额外不必要的<p>标签。

例如，想Markdown文章中添加HTML表格:

This is a regular paragraph.

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

This is another regular paragraph.

注意，Markdown的语法在HTML的块级标签内并不会起作用。比如，你不能再HTML的块级元素内使用Markdown格式的*emphasis*。

HTML的内联标签，比如<span>, <cite>, 或者<del>等等，可以在Markdown正文，列表或者标题等任何地方使用。只要你想，你甚至可以用HTML标签来代替Markdown格式，比如，如果你想用HTML的<a>或<img>标签来替代Markdown的链接或图像语法，直接使用即可。

和HTML的块级元素不同，Markdown的语法在HTML中的内联元素中可以正常使用。

特殊字符的自动转换

在HTML中，有两个字符需要特殊对待:”<”和”&”。”<”符号用于起始标签，”&”符号用于标记HTML实体，如果你想把这两个符号用作普通字符，你必须对它们进行转义，即&lt;和&amp;
“&”符号尤其会让写作者感到困惑。如果你书写’AT&T’，你需要写成’AT&amp;T’。你甚至需要在URL中对’&’符号进行转义。如果你想链接到如下地址:

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

你需要把链接转成:

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

才能放到链接标签的href属性中。这一点是很容易忘记的，这也可能是HTML标准检查所检查到的错误中，数量最多的。

Markdown允许你直接使用这些符号，但是需要留意必要的转义。如果你使用”&”作为HTML元素的实体，Markdown会对其保持不变；否则Markdown会将其转换为”&amp;”。

如果你想要在你的文章中引入版权符号，你可以这样写:

&apm;copy;

这样Markdown对其会保持不变，但是如果你书写:

AT&T

Markdown会将其转换为：

AT&amp;T

类似的，因为Markdown支持行内元素，如果你将”<”作为HTML的标签使用，Markdown会正常对待，但是如果你要书写:

 4 < 5

Markdown会将其转换为

 4 &lt; 5

不过需要注意的是，在code范围内，不论是行内元素还是区块元素，”<”和”&”两个符号都一定会被默认成HTML实体，这个特性使你可以轻松的使用Markdown书写HTML代码(而在HTML语法中，你需要把所有的”<”和”&”都转换为HTML实体，才能在HTML文件中写错HTML代码。)。

块级元素

段落和换行

段落只是由一个或多个连续的行句组成，并且由一个或多个空行分隔开。(空行的定义是显示出来是空行，便被视为空行，一个空行可能什么都不包含，也可能空格或tabs)。一般段落不需要用空格或tabs来缩排。

“一个以上相连接的行句组成”,这句话按时Markdown支持段落内强行断行。这一点和大多数text-to-html格式工具不同(包括 MovableType的「Convert Line Breaks」选项),其他格式会把每个断行都转成<br />标签。

如果你真的想要插入<br />標籤的話，在行尾加上兩個以上的空白，然後按enter。

这样做确实需要花更多的功夫来插入<br />，但是每个换行都转换为<br />的方法在Markdown中并不适合。Markdown中的email风格的区块引用和多段落的清单在使用换行来排版的时候，不但更好用，还更好阅读。

标题

Markdown支持两种风格的标题, Setext和atx.
Setext风格是用横线的形式，”=”表示大标题，”-“表示小标题，例如：

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中创建区块引用。这个效果看起来就像是你使用强制断行，并且在每行开头方式”>”符号:

> 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");

任何标志的文本编辑器都可以轻松使用email风格的区块引用。比如:BBEdit,你可以选取文字然后从选单中选择增加引用级数。

清单

Markdown支持有序清单和无序清单。
无序清单可以使用星号，加好，减号作为标记:

* Red
* Green
* Blue
+ Red
+ Green
+ Blue
- Red
- Green
- Blue

以上三种表示是等价的。

有序清单使用数字加一个英文句号:

1. Bird
2. McHale
3. Parish

需要注意的是，在清单标记上使用的数字并不影响HTML的输出结果。上面的清单所产生的HTML标记为:

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

如果你的清单写成如下形式:

1. Bird
1. McHale
1. Parish

或者

3. Bird
1. McHale
8. Parish

你都会得到同样的HTML输出结果。重点在于，只要你想，你可以在Markdown列表里使用正常顺序，这样Markdown中的数字顺序正好匹配发布的结果。但是这也不是必须的。

如果你使用懒惰的写法，你依然应该用1数字来开头。因为Markdown未来可能支持有序清单的start属性。
清单项目标记通常是放在最左边，但是其实也可以缩排，最多三个空格，列表标记后一定只要要接一个空格或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.

如果列表项被空行分开，Markdown在输出时会用<p>标签来包裹起列表项。比如:

* 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个空格或tabs:

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're
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个空格或两个tabs:

*   A list item with a code block:

        <code goes here>

需要注意的是，某些意外情况下，也有可能产生有序列表，像下面这种写法:

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

Markdown会转换成:

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

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

代码块中一级的缩排——4个空格或一个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语法相关的文件。

分割线

你可以在一行中庸三个火以上的星号、减号、下划线来建立一个分割线。你也可以在星号中插入空白,写法如下:

* * *

***

*****

- - -

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

行内元素

链接

Markdown支持两种形式的链接语法:行内(inline)和参考(reference)两种。
这两种方式链接的文本都放在中括号中”[]”。
要建立行内形式的链接，只需要在方括号后面接着使用小括号，并输入链接地址即可。如果你还想加上链接的title文字，只要在网址后面，用双引号把title文字包裹起来即可，例如：

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

参考形式的链接使用额外的方括号在链接文字的方括号后面，而在第二个方括号里要输入辨识链接的标签:

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

你也可以选择在两个方括号中间加上空格。

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

然后，在文档的任何地方，你可以把这个标签的链接内容定义出来：

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

链接的定义形式为:

  • 方括号，里面输入链接的辨识用的标签
  • 接着一个冒号
  • 接着一个以上的空白或tab
  • 接着链接的网址
  • 选择性的接着title内容，可以用单引号，双引号或者是小括号包裹

以下三种链接定义是等价的：

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

注意：存在一个一直的bug，在Markdown.pl 1.0.1中，会忽略单引号包裹起来的title内容。

链接的网址也可以用尖括号包裹起来

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

为了书写更加美观，你也可以把title属性放在下一行书写，并加上适当的空格和tab

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

链接的定义只会在产生链接的时候用到，并不会直接出现在文件中。
链接标识可以是字母、数字、空白和标点符号。但是不区分大小写。因此下面两个链接是一样的：

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

隐式的链接标记功能会让你省略指定链接标签。这种情况下，链接标记就是链接文字的内容。要使用隐式的链接，只需要在链接文字后面加上中括号。比如，链接Google到Google官网，你可以简单写成：

[Google][]

然后定义链接：

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

由于链接文字的内容中可以包含空格，因此在链接文字中可以有多个单词：

Visit [Daring Fireball][] for more information.

然后定义链接：

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

链接定义可以放在文档中的任何地方。我个人趋向把它们放在链接出现段落的后面。你也可以放在文件最后面，就像注解一样。
下面是一个链接的范例：

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"

使用隐式链接的话，也可以这样写：

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"

上面的两个例子，输出结果如下：

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

下面是用行内形式书写的同一段内容的Markdown文件，作为比较：

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").

参考式的链接并不在于他们好写，而是在于易读。对比上面的例子，使用参考式的链接，段落只有81个字符，而使用行内链接需要176个字符。使用HTML格式来写，会有234个字符。在HTML格式汇总，标签比文字还要多。
使用Markdown的参考式链接，可以让文件更像是浏览器最后产生的结果，让你可以把写标记相关的元数据移到段落文字之外，避免给阅读者造成被打断的感觉。

强调

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>

你可以根据你的喜好进行选择这两种符号，唯一的限制是，你用什么符号开启强调，就要用什么符号结束。
强调也可以直接插在文字中间：

un*frigging*believable

但是如果你的”*”和”_”两边都有空白的话，它们就只会被当成普通的符号。
如果要在文字钱面直接插入普通的星号或下划线，可以用转义符号。

\*this text is surrounded by literal asterisks\*

代码

如果想要在行内书写一小段代码，可以使用”`”包裹。例如：

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>

用反引号包裹代码，也可以包含空格，一个在开始标记后面，一个在结束标记前面。这就允许你在代码的开始和结束位置放置反引号符号。

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

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

输出：

<p>A single backtick in a code span: <code>`</code></p>

<p>A backtick-delimited string in a code span: <code>`foo`</code></p>

在行内代码中，”&”和方括号都会被转成HTML实体。这样便会方便插入HTML源码。

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

详细叙述如下：

  • 一个感叹号!
  • 接着一个方括号，里面放上图片的替代文字
  • 接着一个小括号，里面放上图片链接，最后还可以用引号包住并加上选择性的”title”文字

引用样式的语法如下：

![Alt text][id]

id是图片参考的标记，这和链接的定义相似：

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

目前，Markdown还没有语法可以指定图片的尺寸。如果你有这个需求，可以使用HTML标签<img>。

其他

自动链接

Markdown支持简单的风格来创建网站或email的链接。只需要将链接放入尖括号中。这就是说，如果你想展示链接或email的文本内容，可以像下面这样写：

<http://example.com/>

输出为：

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

自动邮箱链接也很类似。只是Markdown会先做一个编码转换的过程，把文字字符转成16进制编码的HTML实体，这样的格式可以混淆一些不好的邮箱地址收集机器人。例如：

<address@example.com>

Markdown会转换成:

<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语法中有其他意义的符号。例如，如果你想要用星号放在文字旁边但不要出现强调效果(不用<em>标签)，可以这样写:

\*literal asterisks\*

Markdown的元字符包括：

\   反斜线
`   反引号
* 星号
_   下划线
{}  大括号
[]  方括号
()  小括号
# 井号
+ 加好
- 減号
.   英文句点
!   感叹号

参考文献:
[1]. Markdown原版的官方文档
[2]. Markdown原版的官方文档的中文翻译
标签：

相关文章