语法说明

宗旨

马克down 的靶子是促成「易读易写」。

可读性,无论如何,都是最着重的。一份使用 马克down 格式撰写的文书应当能够直接以纯文本公告,况兼看起来不会疑似由大多标签或许格式指令所构成。马克down 语法受到部分既有 text-to-HTML 格式的震慑,包涵 Setext、atx、Textile、reStructuredText、Grutatext和 EtText,而最大灵感来源于其实是纯文本电子邮件的格式。

简单的说, 马克down 的语法全由一些标识所组成,那个标识经过精挑细选,其意义映注重帘。例如:在文字两旁加上星号,看起来就像*强调*。马克down 的列表看起来,嗯,便是列表。马克down 的区块援引看起来就着实像是援用一段文字,就疑似您曾经在电子邮件中见过的那样。

反斜杠

马克down 能够选拔反斜杠来插入一些在语法中有其余意义的号子,比如:假设你想要用星号加在文字旁边的主意来做出重申效果与利益(但不用 <em> 标签),你能够在星号的前方加上反斜杠:

*literal asterisks*

Markdown 帮助以下这个标志后面加上反斜杠来支援插入普通的标志:

   反斜线
`   反引号
*   星号
_   底线
{}  花括号
[]  方括号
()  括弧
#   井字号
+   加号
-   减号
.   英文句点
!   惊叹号

列表

马克down 协理有种类表和冬天列表。

无种类表使用星号、加号或是减号作为列表标识:

*   Red
*   Green
*   Blue

等同于:

+   Red
+   Green
+   Blue

也同样:

-   Red
-   Green
-   Blue

不改变列表则接纳数字接着三个塞尔维亚共和国(Republic of Serbia)语句点:

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 输出。重点在于,你可以让 马克down 文件的列表数字和输出的结果一致,或是你懒一点,你能够完全不用在乎数字的不错。

如果您使用懒惰的写法,建议首先个等级次序最佳也许从 1. 起始,因为 马克down 今后或许会支撑有系列表的 start 属性。

列表项目的识经常是坐落最侧面,可是实际上也能够缩进,最多 3 个空格,项目的识前边则势须要跟着起码多个空格或制表符。

要让列表看起来越来越美好,你能够把内容用固定的缩进整理好:

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

假使列表项目间用空行分开,在出口 HTML 时 马克down 就能够将项目内容用 <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 个空格或是 1 个制表符:

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.

要是你每行都有缩进,看起来会看好比相当多,当然,再一次地,纵然您很懒惰,马克down 也允许:

*   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 个空格或是 2 个制表符:

*   一列表项包含一个列表区块:

        <代码写在这>

理所必然,项目列表很可能会非常大心发生,疑似下边那样的写法:

1986. What a great season.

换句话说,也正是在行首出现数字-句点-空白,要制止那样的光景,你能够在句点后面加上反斜杠。

1986. What a great season.

特殊字符自动转变

在 HTML 文件中,有两个字符供给极其管理: < 和 & 。 < 符号用于初始标签,& 符号则用于标识HTML 实体,假如您只是想要突显这一个字符的原型,你必供给运用实体的款式,疑似 &lt; 和 &amp;

& 字符越发让互联网文书档案编写者受折磨,如若您要打「AT&T」 ,你不可能不要写成「AT&amp;T」。而网址中的 & 字符也要退换。比方您要链接到:

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

您不能够不要把网站转变写为:

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

技能松开链接标签的 href 属性里。不用说也知晓那很轻巧忽略,这也可能是 HTML 标准核准所检查到的荒谬中,数量最多的。

马克down 让你能够自然地书写字符,要求更改的由它来处理好了。假设你使用的 & 字符是 HTML 字符实体的一片段,它会保留最早的风貌,不然它会被撤换到 &amp;。

因此你一旦要在文档中插入三个版权符号 ©,你可以如此写:

&copy;

马克down 会保留它不动。而若你写:

AT&T

Markdown 就能够将它转为:

AT&amp;T

看似的气象也会生出在 < 符号上,因为 Markdown 允许 兼容 HTML ,即使您是把 < 符号作为 HTML 标签的定界符使用,那 马克down 也不会对它做此外转变,不过只要您写:

4 < 5

Markdown 将会把它转变为:

4 &lt; 5

然则须要注意的是,code 范围内,不论是行内仍旧区块, < 和 & 四个暗号都一定会被调换来 HTML 实体,那项特色让你能够很轻易地用 马克down 写 HTML code (和 HTML 相对来讲, HTML 语法中,你要把具备的 < 和 & 都转变为 HTML 实体,手艺在 HTML 文件之中写出 HTML code。)


代码区块

和程序相关的写作或是标签语言原始码平常会有已经排版好的代码区块,平日那几个区块大家并不愿意它以相似段落文件的方法去排版,而是照原本的表率展现,马克down 会用 <pre> 和 <code> 标签来把代码区块包起来。

要在 马克down 中创设代码区块很简短,只要轻松地缩进 4 个空格或是 1 个制表符就能够,比如,上边包车型客车输入:

这是一个普通段落:

    这是一个代码区块。

Markdown 会调换到:

<p>这是一个普通段落:</p>

<pre><code>这是一个代码区块。
</code></pre>

其一每行一阶的缩进(4 个空格或是 1 个制表符),都会被移除,举例:

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 实体,那样的主意令你特别轻易使用 马克down 插入模范用的 HTML 原始码,只需求复制贴上,再增加缩进就足以了,剩下的 马克down 都会帮你管理,例如:

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

代码区块中,平时的 马克down 语法不会被调换,疑似星号便只是星号,那表示您能够很轻便地以 马克down 语法撰写 马克down 语法相关的文书。

区块援用 Blockquotes

马克down 标志区块引用是采纳类似 email 中用 > 的援引情势。倘使您还谙习在 email 信件中的引言部分,你就知道怎么在 马克down 文件中国建工业总会公司立四个区块援引,那会看起来疑似你和谐先断好行,然后在每行的最前方加上 > :

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

马克down 也同意你偷懒只在方方面面段落的第一行最前方加上 > :

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

援用的区块内也得以行使另外的 马克down 语法,包含题目、列表、代码区块等:

> ## 这是一个标题。
> 
> 1.   这是第一行列表项。
> 2.   这是第二行列表项。
> 
> 给出一些例子代码:
> 
>     return shell_exec("echo $input | $markdown_script");

任何类似的文件编辑器都能轻巧地树立 email 型的引用。举个例子在 BBEdit 中,你能够挑选文字后然后从选单中选拔扩展援用阶层

感谢

感谢 leafy7382 补助翻译,hlb、Randylien 帮助润稿,ethantw 的汉字规范格式・CSS Reset, WM 回报文字错误。

感谢 fenprace,addv。

概述

兼容 HTML

马克down 语法的对象是:成为一种适用于互联网的书写语言。

马克down 不是想要代替HTML,以致也绝非要和它好像,它的语法种类很少,只对应 HTML 标识的一小部分。马克down 的构想不是要使得 HTML 文档更便于书写。以小编之见, HTML 已经很轻便写了。马克down 的视角是,能让文书档案更易于读、写和任性改。HTML 是一种发布的格式,Markdown 是一种书写的格式。就这么,Markdown 的格式语法只包含纯文本能够饱含的界定。

不在 马克down 包括范围以内的价签,都得以一向在文书档案里面用 HTML 撰写。不须求卓殊申明那是 HTML 或是 马克down;只要直接加标签就能够了。

要制裁的独有局地 HTML 区块成分――比方 <div><table><pre><p> 等标签,必得在内外加上空行与其余内容区隔离,还要求它们的上马标签与最后标签不可能用制表符或空格来缩进。马克down 的生成器有丰盛智能,不会在 HTML 区块标签外增进不要求的<p> 标签。

事比如下,在 马克down 文件里丰裕一段 HTML 表格:

这是一个普通段落。

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

这是另一个普通段落。

请留心,在 HTML 区块标签间的 马克down 格式语法将不会被管理。举个例子,你在 HTML 区块内接纳 马克down 样式的*强调*会并未有意义。

HTML 的区段(行内)标签如 `、可以在 Markdown 的段落、列表或是标题里随意使用。依照个人习惯,甚至可以不用 Markdown 格式,而直接采用 HTML 标签来格式化。举例说明:如果比较喜欢 HTML 的` 标签,能够直接使用这一个标签,而不用 马克down 提供的链接恐怕图像标签语法。

和处于 HTML 区块标签间分化,马克down 语法在 HTML 区段标签间是一蹴而就的。

自行链接

马克down 协助以相比较简便的全自动链接格局来拍卖网站和电子邮件信箱,只借使用方括号包起来, 马克down 就能够自动把它转成链接。日常网址的链接文字就和链接地址同样,举例:

<http://example.com/>

Markdown 会转为:

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

邮址的机关链接也很临近,只是 马克down 会先做三个编码调换的长河,把文字字符转成 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>

在浏览器里面,这段字串(其实是 <a href="mailto:address@example.com">address@example.com</a>)会形成三个方可点击的「address@example.com」链接。

(这种作法固然能够糊弄不菲的机器人,但并不能够一体挡下来,可是总比什么都不做好些。不管如何,公开你的信箱毕竟会引来广告信件的。)

强调

马克down 使用星号(*)和底线(_)作为标识重申字词的标识,被 * 或 _ 包围的字词会被转成用 <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*

区段成分

图片

很显著地,要在纯文字应用中企图三个「自然」的语法来插入图片是有一定难度的。

马克down 使用一种和链接很平时的语法来标识图片,同样也允许三种体制: 行内式参考式

行内式的图纸语法看起来疑似:

![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"

到前段时间甘休, 马克down 还未曾主意钦定图片的宽高,假使您须要的话,你能够选择普通的 <img> 标签。


区块成分

链接

马克down 协理三种方式的链接语法: 行内式参考式二种方式。

随意是哪个种类,链接文字都是用 [方括号] 来标记。

要成立一个行内式的链接,只要在四方括号后边随着圆括号并插入网站链接就可以,固然您还想要加上链接的 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"

链接内容定义的方式为:

  • 方括号(后面能够接纳性地足够至多多个空格来缩进),里面输入链接文字
  • 进而一个冒号
  • 随时一个上述的空格或制表符
  • 继而链接的网站
  • 选取性地跟着 title 内容,能够用单引号、双引号或是括弧包着

上面那二种链接的定义皆以一致:

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

请注意:有一个已知的标题是 马克down.pl 1.0.1 会忽略单引号包起来的链接 title。

链接网站也得以用方括号包起来:

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

您也能够把 title 属性放到下一行,也得以加一些缩进,若网站太长的话,那样会比较雅观:

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

网址定义唯有在暴发链接的时候使用,并不会平素现身在文件之中。

链接辨别标签可以有字母、数字、空白和标点符号,不过并有别于轻重缓急写,由此下边七个链接是一模二样的:

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

隐式链接标志职能让你能够简简单单钦定链接标识,这种状态下,链接标志会视为等同链接文字,要用隐式链接标志只要在链接文字后边加上三个空的方括号,借使您要让 "谷歌" 链接到 google.com,你能够简化成:

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

地点三种写法都会生出下边包车型地铁 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>

上边是用行内式写的同样一段内容的 马克down 文件,提供作为比较之用:

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 格式中,标签比文本还要多。

动用 马克down 的仿照效法式链接,能够让文件更疑似浏览器最终产生的结果,令你能够把有些符号相关的元数据移到段落文字之外,你就足以扩展链接而不让作品的读书认为被打断。

其它

代码

假诺要标志一小段行内代码,你可以用反引号把它包起来(`),例如:

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 原始码变得很轻巧,Markdown 会把下部这段:

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>

段落和换行

贰个 马克down 段落是由三个或多少个接二连三的文本行组成,它的光景要有二个上述的空行(空行的概念是突显上看起来疑似空的,便会被视为空行。比如说,若某一行只含有空格和制表符,则该行也会被视为空行)。普通段落不应该用空格或制表符来缩进。

「由一个或四个三回九转的文本行组成」那句话实际暗中提示了 马克down 允许段落内的强迫换行(插入换行符),这一个天性和任何大部的 text-to-HTML 格式区别样(满含 Movable Type 的「Convert Line Breaks」选项),别的的格式会把种种换行符都转成 <br /> 标签。

如果你确实想要信任 马克down 来插入 <br /> 标签的话,在插入处先按入多少个以上的空格然后回车。

真的,必要多费点事(多加空格)来发出 <br /> ,可是不难地「各种换行都更改为 <br />」的措施在 马克down 中并不切合, Markdown 中 email 式的 区块援引 和多段落的 列表 在运用换行来排版的时候,不但更好用,还更方便阅读。

分隔线

你能够在一行中用两个以上的星号、减号、底线来树立七个分隔线,行内无法有别的东西。你也能够在星号或是减号中间插入空格。上边每个写法都足以建立分隔线:

* * *

***

*****

- - -

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

标题

马克down 扶助二种题指标语法,类 Setext 和类 atx 形式。

类 Setext 格局是用底线的款型,利用 = (最高阶标题)和 - (第二阶标题),比如:

This is an H1
=============

This is an H2
-------------

其余数据的 = 和 - 都可以有功力。

类 Atx 情势则是在行首插入 1 到 6 个 # ,对应到标题 1 到 6 阶,举例:

# 这是 H1

## 这是 H2

###### 这是 H6

你能够选拔性地「闭合」类 atx 样式的标题,那纯粹只是美观用的,假诺认为那样看起来相比较安适,你就能够在行尾加上 #,而行尾的# 数量也不用和最初一样(行首的井字符数量调控题目标阶数):

# 这是 H1 #

## 这是 H2 ##

### 这是 H3 ######

本文由银河网址发布于银河网址,转载请注明出处:语法说明

您可能还会对下面的文章感兴趣: