Markdown Syntax Documentation

UpDate 2018-08-05 1533466823

Author unnamed

Mail indv.zhang@foxmail.com

Tip Please feel free to contact me via mail above for any confusion or suggestions

INTRODUCTION

This blog is intended to translate the markdown syntax documentation into Chinese for personal reasons. It would make me feel good if there is some possibility for helping somebody. If you guys want to read the original version of markdown syntax documentation, please click here. In the end, Hope you enjoy this blog :-)

OVERVIEW

PHILOSOPHY/Markdown哲学思想

Markdown致力于实现 易于读写 这一特性。

在所有的特性中，可读性 是胜于一切的。Markdown格式的文档应该像普通文本一样可以发布，而不是看起来像是标记了标签或者标记了格式化说明。虽然Markdown语法受到了几个现有的 text-to-HTML 过滤器的影响，但Markdown语法最大的灵感来源于纯文本电子邮件的格式（现有的 text-to-HTML 过滤器包括 Setext, atx, Textile, reStructuredText, Grutatext, EtText）。

因此，Markdown语法完全由标点及字符组成。同时，为了使得我们看到这些标点字符就易于联想到其功能，Markdown对标点字符的挑选是精挑细选的。比如说，一个单词两边加了字符“*”，就会使得这个单词看起来有点强调的意味，而Markdown的语法将会为其显示为斜体，.是不是强调了？而Markdown语法下的表格，emmmm，其实就是表格的样子（hiahiahia~）。 甚至 块引用 看起来就像被引用的文本段落。

INLINE HTML/内联HTML

Markdown语法致力于一个目的：被作为网页 写作 的格式来使用。

Markdown不是HTML的替代品，甚至和HTML都不是很接近。Markdown的语法很小，它只对应了HTML标签的一个很小的子集。Markdown并 不是 要创造一种更容易 插入HTML标签 的语法。在 JOHN GRUBER 看来，HTML标签已经很易于插入了。Markdown的意义在于使得读写与编辑文字更容易。HTML是一种 发布 格式；Markdown是一种 写作 格式。因此，Markdown的格式化语法仅仅只能解决用纯文本传达的写作问题。

对于Markdown语法没有覆盖到的一些标记，你只需要简单的使用HTML自身就可以了。同时，你完全不需要去添加前缀或者采用分隔来表明你正在从Markdown语法切换到HTML语法。你只需要，标签即可。

唯一的限制就是块级别(block-level)的HTML元素必须通过空行与周围内容分开，并且块的开始和结束标签不应该使用制表符或者空格进行缩进——例如<div>, <table>, <pre>, <p>等等。另外，Markdown聪明到不会在HTML块级别的标签周围去添加额外的（不需要的）<p>标签。

例如，添加一个HTML表单到Markdown文章中：

HTML表单

但其实，HTML表单后面是这样写的：

This is a regualr paragraph.

<table>
    <tr>
        <td>第一行第一列</td>
        <td>第一行第二列</td>
    </tr>
    <tr>
        <td>第二行第一列</td>
        <td>第二行第二列</td>
    </tr>
</table>

This is another regular paragraph.

请注意，Markdown的格式化语法在块级别的HTML标签中是不起作用的。比如，在一个HTML块内部，你不能使用Markdown风格的强调符号*（* emphasis *）。

跨级水平(span-level)的HTML标签（<span>, <cite>, <del>）可以在Markdown中的任何地方使用（段落，表单，头部）。只要你愿意，你甚至可以使用HTML标签代替Markdown格式；比如，如果你更倾向于使用HTML的<a>或者<img>标签来代替Markdown的链接或者图象语法，干就完了！

和块级别的HTML标签不同的是，在跨级水平的HTML标签内，Markdown的语法还是有效果的。

AUTOMATIC ESCAPING FOR SPECIAL CHARACTERS/自动退出特殊字符

在 HTML 中，有两个字符需要特殊对待：< 和 & 。左尖括号<被用于作为开始标签；&用于表示HTML实体。如果你想将它们作为文字字符使用，就必须要将它们作为实体进行转义，比如&lt;和&amp;。

特别地，&尤其困扰网页开发者。如果你想写AT&T，你得写成AT&amp;T。你甚至在URLs中也需要转义。比如说，如果你想在标签href中写个链接为：

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

那你就得这样写：

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

比较烦的是，转义这种操作很容易忘掉。而且，在一些网站上出现HTML验证错误，最大可能性就是因为没有进行转义。

Markdown可以让你很自然的使用这些字符，它会帮你关注到所有需要注意的转义。如果你在某个HTML的实体中使用了&字符，该字符会保持不变，依然是&；另一方面，如果你直接使用&amp;，markdown也会将其转义为&(if you use an ampersand as part of an HTML entity, it remains unchanged; otherwise it will be translated into &amp;)。

所以，如果你想在文章中写一个版权标志©,那么你只需要写&copy;即可，Markdown会将其转义为版权标志。但是如果你写AT&T，Markdown会自己将其识别为AT&amp;T，因此在屏幕上的表现依然为AT&T。同样的，由于Markdown支持inline HTML，如果你使用尖括号作为HTML标签的分隔符，Markdown也会将尖括号看作HTML标签的分隔符看待，但如果你写4 < 5，Markdown就会将其识别为4 &lt; 5。

在Markdown代码内部，尖括号和&通常是自动编码的。这就使Markdown用来写HTML代码很方便。（对于原始的HTML，它是一堆HTML语法且对于编写很不友好的一种格式，因为每一个<和&都需要被转义。）

BLOCK ELEMENTS/块元素

PARAGRAPHS AND LINE BREAKS/段落和换行

段落只是一行或多行连续的文本，并且被一个或多个空行分隔。（空行就是任何看起来像是空行的行——这样理解，一行只包含空格或者制表符(Tabs)的也被看作是空行。）正常的段落不能使用空格或者制表符进行缩进。

“一行或多行连续的文本”规则的含义是指Markdown支持“hard-wrapped”文本段落。这和大多数text-to-HTML格式器（包括Movable Type的"Convert Line Breaks"选项）有很大区别，而这些格式器会将段落中每一行的换行符都转译为一个<br />标签。

当你确实想要使用Markdown插入<br />的时候，你就两个或更多空格来结束行，然后键入回车。(When you do want to insert <br /> break tag using Markdown, you end a line with two or more spaces, then type return.)

是的，创建一个<br />有点困难，但是“每一个换行都是一个<br />”的规则不适用于Markdown。当你使用硬中断格式化的时候，Markdown的邮件风格<u>blockquoting</u>和多段落<u>list items</u>效果更好——看起来效果更好。

HEADERS/标题

Markdown支持两种风格的标题，Setext和atx。

Setext风格的标题是使用=符号（一级标题）和-符号（二级标题）作为“下划线”来使用的。比如：

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

无论=符号和-符号的个数有多少，这个规则都将起作用。

Atx风格的标题在行首使用1到6个#哈希字符，对应于六个级别层次的标题。比如：

# This is an H1
## This is an H2
###### This is an H6

当然了，你也可以使用#哈希字符将标题对称化，这个单纯是为了美观——如果你觉得好看的话。标题右边的字符个数甚至都不需要与标题左边的字符个数保持一致（标题左边的字符个数决定了标题的等级。）比如：

# This is an H1 #
## This is an H2 ##
### This is an H3 ######

BLOCKQUOTES/块引用

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.

挺好看的对不对，其实是这样写的：

> 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's some example code:

return shell_exec("echo $input | $markdown_script");

但其实外表里面是这样子的：

> ## 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，你就可以从文本菜单栏中进行选择Increase Quote Level。

LISTS/列表

Markdown支持有序（数字编号）和无序（项目符号）的列表。

无序列表使用星号（*）、加号（+）、连字符（-）来作为列表标识符（这几个列表标识符可以互换），比如列表如下：

  • Red
    • Green
      • Blue

其实内部可以这样实现：

实现方法一：
* Red
    * Green
        * Blue

实现方法二：
+ Red
    + Green
        + Blue

实现方法三：
- Red
    - Green
        - Blue

实现方法四：
* Red
    + Green
        - Blue

有序列表使用数字之后跟句点即可（英文句点）：

  1. Bird
  2. McHale
  3. Parish

Markdown内部就是这么写的：

1. Bird
2. McHale
3. Parish

要注意的是，用于标识列表的实际数字对Markdown产生的HTML输出文件没有任何影响。上面的列表用HTML Markdown生成，会是这个样子：

HTML list

内部源码是这样写的：

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

如果你在Markdown中用其他的语句来写，你依然会得到与上面这个列表一模一样的HTML结果。比如这些结果：

  1. Bird
  2. McHale
  3. Parish

or

  1. Bird
  2. MaHale
  3. Parish

其实内部源码的其他语句是这样子的

1. Bird
1. McHale
1. Parish

or

3. Bird
1. McHale
8. Parish

关键在于，只要你想，你就可以在你的Markdown有序列表中使用序数，而且不管你的序数是怎样的，你发布的HTML中的数字会和你Markdown源文件中的数字进行匹配，然后排序输出。但是如果你是个懒癌患者，你也大可不必这样。

如果你确实懒于列数字，那你就将数字1作为你的列表首个标识符，Markdown会自动给你把后续的数字列出来。在以后，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.

好像并没有什么区别是吧，也确实是这样，因为这里只是强调你可以手动把除首行之外其他行的缩进调整的一致。但是如果你是懒癌患者，不想手动调整缩进来达到悬挂缩进的效果，你也可以这样写内部源码，效果是一样的：

*   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>标签来包裹内容，比如，如果你在Markdown中这样写：

* Bird
* Magic

那么在HTML的结果文件中，会转化为：

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

但如果你这么写Markdown：

* Bird

* Magic

那么在HTML的结果文件中，会转化为：

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

列表可能会包含多个段落。在每一个列表中的子段落，必须缩进四个空格或者一个制表符。效果就像这样：

  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.

而内部实现是：

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.

内部实现如下：

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

内部实现如下：

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

如果要想在列表中放一个代码块，代码块就需要被缩进两次，也就是缩进八个空格或者两个制表符，效果如下：

  • A list item with a code block:

    <code goes here>

内部实现如下：

*   A list item with a code block:

        <code goes here>

需要注意的是，我们在写Markdown的时候会不经意间就触发了有序列表的创建，就像这样：

  1. What a great season
  2. trigger an ordered list by accident

但其实我们想写的是1986. What a great season，但是当我们1986.写完之后列表就被我们不经意间创建了。这是因为我们在行首进行了 number-period-space 的连续操作，也就是数字、句号和空格的连续操作。要避免列表的创建，我们可以对句号.进行转义来实现：

1986. What a great season.

There is no list here.

内部是这样写的：

1986\. What a great season.
There is no list here.

CODE BLOCKS/代码块

预格式化的代码块用于撰写程序或者标识源代码。代码块的那些行是被字面解释的，而不是生成正常的段落。Markdown用<pre>和<code>标签来包裹代码块。

要在Markdown中形成代码块，只需简单的用至少四个空格或一个制表符缩进代码块的每一行即可。比如：

This is a normal paragraph:

This is a code block

内部实现为：

This is a normal paragraph:

    This is a code block.

或者采用这样的内部实现：

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

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

其效果表现为：

效果表现

从代码块中的每一行都删除一级缩写——四个空格或一个制表符。像这样：

Here is an example of AppleScript:

tell application "Foo"
    beep
end tell
example

代码块会持续到没有缩进的某行（或者文章的最后）。

在代码块内，符号&和尖括号（<和>）会自动被转为HTML实体。这种做法就使得Markdown很容易包含示例的HTML源代码——只用粘贴和缩进。Markdown会处理编码的&和尖括号的信息。比如：

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

常规的Markdown语法不会在代码块内被处理。比如，星号在代码块内就仅仅只是字面意义上的星号。这意味着使用Markdown撰写Markdown自身的语法也是很方便的。

HORIZONTAL RULES/水平线规则

你可以通过在一行上放置三个或更多的连字符、星号或者下划线来生成一个水平规则的标签（<hr />）。如果你愿意，你也可以在连字符或者星号中间使用空格。水平线效果如下：

其实内部是这样实现的：

* * *
***
*****
- - -
_______________________________

SPAN ELEMENTS/跨越元素

LINKS/链接

Markdown支持两种风格的链接：内联和引用。

在两种风格中，链接文本都由[方括号]分隔。

要创建内联链接，就在链接文本的结束方括号后面立即用上一组常规括号。在常规括号内部，放上你想链接到的URL地址，以及链接的显示标题，显示标题用引号括起来，但标题并不是必要的，也可以不写。比如：

This is an example inline link.

This link has no title attribute.

内部是这样实现的：

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

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

或者这样：

example

内部是这样实现的：

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

引用风格的链接使用另一组方括号，在方括号内部放置你所选择的链接认证标签：

This is an example reference-style link.

你可以选择性的使用空格来分开括号组：

This is an example reference-style link.

然后，你就可以在文档的任何位置定义你的链接标签，一行一个，像这里：

为什么“像这里”后面什么都没有呢？按道理这里应该有一个示例才对，这是因为我们在文档任何位置定义的链接标签到最后生成的HTML或者PDF文档，这里都不会明文显示，但其实在Markdown的源文档中是有内容存在的，这些内容就是：

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

内容解释：

  • 方括号包含了链接标识符（可选择性的由左边缘缩进至多三个空格）；
  • 紧跟一个冒号；
  • 紧跟一个或多个空格（或者制表符）；
  • 紧跟链接的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 中有一个已知的BUG，这个BUG会阻止单引号用于分隔链接标题。

链接URL也可选择性的使用尖括号来包裹：

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

你也可以将标题属性放置在下一行并且使用额外的空格或者制表符来填充，这种做法对于长度较长的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

然后定义链接：[Google]: http://google.com/

由于链接名称可能包含空格，因此这个快捷方式甚至对文本中的多个单词都是有效的：

Visit Daring Fireball for more information.

内部实现为：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"

上面的两种做法都将产生同样的HTML结果：

example

HTML是这样内部实现的：

<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 than from Yahoo or MSN.

内联的实现方式为：

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

引用风格的链接重点不在于它们更容易书写，而在于如果采用引用风格的链接，你的Markdown源文件可读性更好一些。通过比较上面这些例子：使用引用风格链接，段落自身仅有81个字符长，使用内联风格链接，就有176个字符长，而源生的HTML实现方式，有234个字符长。在源生的HTML中，还有更多的标签在。

使用Markdown的引用风格链接，Markdown源文档更接近于在浏览器中呈现的最终输出。Markdown允许你移除段落中标签相关的属性数据，这样就能让你在添加链接的同时还步破坏你的文档叙述流程。

EMPHASIS/强调

Markdwon将星号（*）和下划线（_）看作是强调的提示符号。用*号或者_包括的文本将会视作是HTML中的<em>标签；而双重的*或者_将会被是视作是HTML中的<strong>标签。比如这样的效果：

single asterisks

single underscores

double asterisks

double underscores

是这样来做的：

*single asterisks*
_single underscores_
**double asterisks**
__double underscores__

而这样的效果：

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

效果为：unfriggingbelievable

但是如果你在星号或者下划线周围放了空格，那星号和下划线就被当作字面意义上的星号和下划线来理解。

在可能会用于强调意义的位置产生字面意义上的星号和下划线，你可以将字符转义，比如：

* this text is surrounded by literal asterisks *

真实写法为：\* this text is surrounded by literal asterisks \*

CODE/代码

要表明一段代码，用反引号（`）来包裹这段代码即可。和预格式化的代码块不同，反引号可以指示在常规段落内的代码。比如：

Use the printf() function.

真实写法为：Use the `printf()` function.

和这样的HTML写法效果一样：<p>Use the <code>printf()</code> function.</p>

在一段代码中为了包含反引号，你可以使用多个反引号作为开始结束的分隔符：

There is a literal backtick(`)here.

真实写法为：`` There is a literal backtick(`) here. ``

和这样的HTML写法效果一样：<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`

真实实现为：

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

HTML的实现方式为：

<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标签。在输出HTML结果的时候，Markdown会将这样的写法：

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

转译为这样的html写法：

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

你也可以通过写：

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

来产生以下的HTML效果：

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

IMAGES/图象

不可否认，设计一种“自然”语法来将图像放入纯文本文档格式是相当困难的。

Markdown尝试使用一种类似于链接的图象语法，有两种风格：内联和引用。

内联图象语法看起来是这样的：

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

语法解释：

  • 一个感叹号：！；
  • 接着是一组方括号，包含了图象的alt属性文本；
  • 接着是一组常规括号，包含了URL或者图象的路径，以及一个可选的标题属性（由单引号或双引号包裹）；

引用风格的图象语法看起来是这样的：

![Alt text][id]

id就是定义的图象引用的名称。图像引用的定义是使用的与链接引用相同的语法。

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

在撰写本文的时候，Markdown没有指定图象尺寸的语法；如果这对你很重要，你可以使用常规的HTML的<img>标签。

MISCELLANEOUS/杂项

AUTOMATIC LINKS/自动链接

Markdown支持快照风格来为URL和邮件地址创建“自动”链接：只需要为URL或者邮件地址用尖括号包裹即可。这就意味着，如果你想展示一个明确的URL或者邮件地址文本，并且也想使它为可点击的，你就可以这样写：

<http://example.com/>

Markdown会将这个转译为HTML格式：

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

电子邮件地址的自动链接的工作方式类似，但Markdown还会执行一些随机十进制和十六进制实体编码，以帮助模糊您的地址从地址获取垃圾邮件。比如，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”。

（这种实体编码的技巧确实会愚弄一些，不能说特别多，地址采集机器人，但肯定不能愚弄所有的。但总好过没有。但是一个地址以这种方式公开可能最终会开始接收垃圾邮件。）

BACKSLASH ESCAPES/反斜线转义

Markdown允许你去使用反斜线转义去生成字面意义上的字符，否则这些字符可能在Markdown语法中有其特殊的意义。例如，如果你想要在一个单词周围用字面意义的星号，你可以在星号之前使用反斜线（而不是HTML标签<tag>），就像这样：

\*literal asterisks\*

Markdown为下面的字符提供了反斜线转义

characters meaning
\ backslash 反斜线
` backtick 反引号
* asterisk 星号
_ underscore 下划线
{} curly braces 花括号
[] square brackets 方括号
() parentheses 常规括号
# hash mark 哈希字符
+ plus sign 加号
- minus sign（hyphen） 减号（连字符）
. dot 点
！ exclamation mark 感叹号
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 194,911评论 5赞 460
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 82,014评论 2赞 371
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 142,129评论 0赞 320
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 52,283评论 1赞 264
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 61,159评论 4赞 357
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 46,161评论 1赞 272
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 36,565评论 3赞 382
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 35,251评论 0赞 253
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 39,531评论 1赞 292
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 34,619评论 2赞 310
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 36,383评论 1赞 326
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 32,255评论 3赞 313
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 37,624评论 3赞 299
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 28,916评论 0赞 17
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 30,199评论 1赞 250
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 41,553评论 2赞 342
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 40,756评论 2赞 335

推荐阅读更多精彩内容