Markdown 语法 API
Markdown：语法
概观
哲学
Markdown旨在尽可能易于阅读和易于编写。
但是，可读性强调一切。Markdown格式的文档应该以纯文本的形式发布，而不会看起来像标签或格式化指令。尽管Markdown的语法受到了几种现有的文本到HTML过滤器的影响，包括 Setext， atx， Textile， reStructuredText，Grutatext， 和 EtText ，Markdown语法的最大灵感来源是纯文本电子邮件的格式。
为此，Markdown的语法完全由标点字符组成，标点字符经过仔细选择以便看起来像他们的意思。 例如，一个词的星号实际上看起来像 *强调*。 Markdown列表看起来就像列表。 即使blockquotes看起来像引用的文本段落，假设你曾经使用过电子邮件。
内联HTML
Markdown的语法仅用于一个目的：用作网络 书写 的格式。
Markdown不是HTML的替代品，甚至不接近它。 它的语法非常小，仅对应于HTML标签的一小部分。 这个想法 并不是 创建一个使插入HTML标签更容易的语法。 在我看来，HTML标签已经很容易插入。 Markdown的想法是让阅读，写作和阅读变得容易编辑散文。 HTML是一种 发布 格式; Markdown是一种 书写 格式。 因此，Markdown的格式化语法只能解决以纯文本形式传达的问题。
对于Markdown语法未涉及的任何标记，您只需使用HTML本身。 没有必要在前言或分隔它以表明您正在从Markdown切换到HTML; 你只需使用标签。
唯一的限制是块级HTML元素 - 例如 <div>， <table>， <pre>， <p> 等等。必须通过空行将其与周围内容分开，并且块的开始和结束标记不应该用制表符或空格缩进。 Markdown足够智能，不会在HTML块级标签周围添加额外的（不需要的） <p> 标签。
例如，要将一个HTML表添加到Markdown文章中：
这是一个正常的段落。
1 | <table> |
这是另一个常规段落。
请注意，Markdown格式化语法不在块级HTML标记中处理。 例如，您不能在HTML块中使用Markdown风格 *重点*。
跨度级HTML标记 - 例如 <span>， <cite> 或 <del> - 可用于Markdown段落，列表项目或标题中的任何位置。 如果你愿意，你甚至可以使用HTML标签而不是Markdown格式; 例如 如果您希望使用HTML <a> 或 <img> 标记而不是Markdown的链接或图像语法，请继续前进。
与块级HTML标签不同，Markdown语法 在 跨度级别标签内处理。
自动转义特殊字符
在HTML中，有两个字符需要特殊处理： < 和 &。 左尖括号用于启动标签; ＆符号用于表示HTML实体。 如果你想用它们作为文字字符，你必须将它们作为实体转义，例如 < 和 &。
特别是对于网络编写者来说，＆符号是很困难的。 如果你想写’AT&T’，你需要写’AT&T‘。 您甚至需要在网址中跳过＆符号。 因此，如果你想链接到：
http://images.google.com/images?num=30&q=larry+bird
您需要将URL编码为：
http://images.google.com/images?num=30&q=larry+bird
在你的锚标记 href 属性中。 不用说，这很容易被遗忘，并且可能是在其他标记良好的网站中最常见的HTML验证错误来源。
Markdown允许您自然使用这些角色，并为您处理所有必要的转义。 如果使用＆符号作为HTML实体的一部分，则它保持不变; 否则它将被翻译成 &。
所以，如果你想在你的文章中包含一个版权符号，你可以写：
©
Markdown将不再支持它。 但是如果你写：
AT&T
Markdown会将其转化为：
AT&T
同样，由于Markdown支持 嵌入式HTML，因此如果您使用尖括号作为HTML标签的分隔符，Markdown会像这样对待它们。 但是如果你写：
4 < 5
Markdown会将其转化为：
4 < 5
但是，在Markdown代码跨度和块内部，尖括号和＆符号 总是 自动编码。 这使得使用Markdown很容易编写HTML代码。 （与原始HTML相反，这是一种用于编写HTML语法的可怕格式，因为您的示例代码中的每个 < 和 & 都需要被转义。）
块元素
段落和换行符
段落只是一个或多个连续的文本行，由一个或多个空行分隔。 （空白行是任何看起来像空行的行 - 只包含空格或制表符的行被认为是空白。）普通段落不应该用空格或制表符缩进。
“一条或多条连续文本”规则的含义是Markdown支持“硬包装”文本段落。 这与大多数其他文本到HTML格式化程序（包括Movable Type的“Convert Line Breaks”选项）有很大不同，它将段落中的每个换行符转换为一个 <br /> 标记。
当你 想要 使用Markdown插入一个 <br /> 中断标签时，可以用两个或多个空格结束一行，然后输入返回。
是的，这需要花费更多的努力来创建一个 <br /> ，但是一个简单的“每行换行符都是 <br /> ”规则对于Markdown来说不起作用。 Markdown的电子邮件风格的 块引用 和多段 列表项 最适合 - 并且看起来更好 - 当您用严格的休息格式化它们时。
头
Markdown支持两种标题， [Setext] [1] 和 [atx] [2]。
Setext风格的标题是使用等号（用于第一级标题）和破折号（用于第二级标题）的“下划线”。 例如：
这是H1
=============
这是H2
-------------
任何数字的下划线 = 或 - 将起作用。
Atx风格的标题在行首使用1-6个哈希字符，对应于标题级别1-6。 例如：
# 这是H1
## 这是H2
###### 这是一个H6
或者，你可以“关闭”atx风格的头文件。 这纯粹是美容 - 如果你认为它看起来更好，你可以使用它。 结束哈希值甚至不需要匹配用于打开头的哈希数。 （开放散列的数量
确定标题级别。）：
# 这是H1 #
## 这是H2 ##
### 这是一个H3 ######
引用文字
Markdown使用电子邮件风格的 > 字符进行区块引用。如果您熟悉在电子邮件中引用文本段落，那么您知道如何在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.
Blockquotes可以包含其他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");
任何体面的文本编辑器都应该使电子邮件式引用变得容易。 例如，使用BBEdit，您可以进行选择并从文本菜单中选择“提高报价级别”。
清单
Markdown支持有序（编号）和无序（项目符号）列表。
无序列表使用星号，加号和连字符 - 可互换
– 作为列表标记：
* Red
* Green
* Blue
相当于：
+ Red
+ Green
+ Blue
和：
- Red
- Green
- Blue
有序列表使用数字后跟句点：
1. Bird
2. McHale
3. Parish
请注意，用于标记列表的实际数字对Markdown产生的HTML输出没有影响。 从上面的列表产生的HTML Markdown是：
1 | <ol> |
如果你改为在Markdown中写下这样的列表：
1. Bird
1. McHale
1. Parish
甚至：
3. Bird
1. McHale
8. Parish
你会得到完全相同的HTML输出。 关键是，如果你愿意，你可以在你订购的Markdown列表中使用序号，以便你的源代码中的数字与发布的HTML中的数字相匹配。 但是如果你想懒惰，你不需要。
但是，如果确实使用懒惰列表编号，则仍应以数字1开始列表。在将来的某个时间，Markdown可能支持以任意数字开始的有序列表。
列表标记通常从左边界开始，但可以缩进最多三个空格。 列表标记后面必须跟一个或多个空格或制表符。
为了使列表看起来不错，您可以使用悬挂缩进来包装项目：
* 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会将这些项目包装在HTML输出中的 <p> 标签中。 例如，这个输入：
* Bird
* Magic
将变成：
1 | <ul> |
但是这个：
* Bird
* Magic
将变成：
1 | <ul> |
列表项目可能由多个段落组成。 列表项中的每个后续段落都必须缩进4个空格或一个制表符：
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个空格或两个制表符：
* 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个标签。 例如，给出这个输入：
This is a normal paragraph:
This is a code block.
Markdown将产生：
1 | <p>This is a normal paragraph:</p> |
从代码块的每一行删除一级缩进 - 4个空格或1个制表符。 例如，这个：
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
将变成：
1 | <p>Here is an example of AppleScript:</p> |
一个代码块会一直持续到它没有缩进的一行（或文章结尾）。
在代码块中，＆符号（&）和尖括号（<和>）会自动转换为HTML实体。 这使得使用Markdown包含示例HTML源代码变得非常简单 - 只需粘贴并缩进即可，Markdown将处理编码＆符号和尖括号的麻烦。 例如，这个：
1 | <div class="footer"> |
将变成：
1 | <pre><code><div class="footer"> |
定期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.
会产生：
1 | <p>This is <a href="http://example.com/" title="Title"> |
如果您指的是同一台服务器上的本地资源，则可以使用相对路径：
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"
那是：
- Square brackets containing the link identifier (optionally
indented from the left margin using up to three spaces); - followed by a colon;
- followed by one or more spaces (or tabs);
- followed by the URL for the link;
- optionally followed by a title attribute for the link, enclosed
in double or single quotes, or enclosed in parentheses.
以下三个链接定义是等价的：
[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"
您可以将title属性放在下一行，并使用额外的空格或制表符来填充，这对于更长的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"
使用隐式链接名称快捷方式，可以改为编写：
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"
以上两个示例都会生成以下HTML输出：
1 | <p>I get 10 times more traffic from <a href="http://google.com/" |
为了比较，这里是使用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将星号（*）和下划线（_）作为重点指标。 用一个 * 或 _ 包裹的文本将用一个HTML <em> 标签包装; 用两个 * 或 _ 将被包含一个HTML <strong> 标签。 例如，这个输入：
*single asterisks*
_single underscores_
**double asterisks**
__double underscores__
会产生：
1 | <em>single asterisks</em> |
你可以使用你喜欢的任何风格; 唯一的限制是必须使用相同的字符来打开和关闭重点范围。
强调可以用在词的中间：
un*frigging*believable
但是如果用空格包围 * 或 _ ，它将被视为文字星号或下划线。
要在原本用作强调分隔符的位置生成文字星号或下划线，可以使用反斜杠进行转义：
\*this text is surrounded by literal asterisks\*
代码
为了表示一段代码，用反引号引起来（`）。 与预格式化代码块不同，代码范围指示正常段落内的代码。 例如：
Use the `printf()` function.
会产生：
1 | <p>Use the <code>printf()</code> function.</p> |
要在代码范围内包含文字反引号字符，可以使用多个反引号作为开始和结束分隔符：
``There is a literal backtick (`) here.``
这将产生这样的结果：
1 | <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` ``
会产生：
1 | <p>A single backtick in a code span: <code>`</code></p> |
通过代码跨度，＆符号和尖括号会自动编码为HTML实体，这样可以轻松包含示例HTML标记。 Markdown会变成这样：
Please don't use any `<blink>` tags.
成：
1 | <p>Please don't use any <code><blink></code> tags.</p> |
你可以写这个：
`—` is the decimal-encoded equivalent of `—`.
产生：
1 | <p><code>&#8212;</code> is the decimal-encoded |
图片
无可否认，设计用于将图像置于纯文本文档格式的“自然”语法相当困难。
Markdown使用图像语法，旨在类似链接的语法，允许两种样式：内联 和 引用。
内联图像语法如下所示：
那是：
- 感叹号：
!; - 然后是一组方括号，其中包含图像的
alt属性文本; - 接着是一组括号，其中包含图像的URL或路径，以及用双引号或单引号括起来的可选
title属性。
参考风格的图像语法如下所示：
![Alt text][id]
其中“id”是定义的图像引用的名称。 图像引用是使用与链接引用相同的语法定义的：
[id]: url/to/image "Optional title attribute"
在撰写本文时，Markdown没有指定图像尺寸的语法; 如果这对你来说很重要，你可以简单地使用普通的HTML标签 <img> 标签。
杂项
自动链接
Markdown支持创建URL和电子邮件地址的“自动”链接的快捷方式：只需使用尖括号围绕URL或电子邮件地址即可。 这意味着如果你想显示一个URL或电子邮件地址的实际文本，并且它也是一个可点击的链接，你可以这样做：
<http://example.com/>
Markdown将把它变成：
1 | <a href="http://example.com/">http://example.com/</a> |
电子邮件地址的自动链接的工作方式与此类似，但Markdown还会执行一些随机化的十进制和十六进制实体编码，以帮助屏蔽地址收集spambots的地址。 例如，Markdown会变成这样：
<address@example.com>
变成这样的东西：
1 | <a href="mailto:addre |
这将在浏览器中呈现为“address@example.com”的可点击链接。
（这种实体编码的技巧确实会欺骗很多（如果不是绝大多数）地址获取机器人，但它绝对不会欺骗所有这些机器人。总比没有好，但以这种方式发布的地址可能最终会开始接收 垃圾邮件。）
反斜线转义
Markdown允许您使用反斜线转义来生成文字字符，否则这些字符在Markdown的格式化语法中会有特殊含义。 例如，如果您想用文字星号（而不是HTML <em> 标签）标记单词，则可以在星号之前使用反斜杠，如下所示：
\*literal asterisks\*
Markdown为以下字符提供反斜杠转义符：
\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark