陈颂光
全栈工程师,能够独立开发从解释器到网站和桌面/移动端应用的各类软件。
关注我的 GitHub

Markdown概览

我们有很多基于纯文件的排版语言,从Roff、TeX、HTML到各种wiki(如dokuwiki和mediawiki)。Markdown和各种wiki语言比较类似,都用于自动生成HTML网页,并让排版前的源文件保持一定的可读性。近年,由于Github、Gitlab和一些博客等网站把markdown作为首选的排版语言,markdown有一定的流行度。

基本语法

Markdown的文档见https://daringfireball.net/projects/markdown/。以下是主要内容:

markdown与HTML

在markdown文档中可直接用HTML,但块级的HTML元素如 <div><table><pre><p>等须以空行与其它内容分开,并且用空格或制表符缩进,以防加入多余的<p>或作markdown内容处理。例如要加入一个表格,可用:

This is a regular paragraph.

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

This is another regular paragraph.

而其它标签间的内容会被markdown处理。

markdown中&<会自动判断是否应生成&amp;&lt;,不用手动转义。当然你也可以用HTML中各种符号实体。不过,在markdown的代码引用和块中,它们总被自动转义。

块元素

段落和断行

段落之间由空行(可有空格和制表符)分隔,不要缩进。段落内的分行对输出不重要。

标题

标题的一种写法为:

这是 H1
=============

这是 H2
-------------

其中=-个数不重要。

标题的另一种写法为:

# 这是 H1

## 这是 H2

###### 这是 H6

其中开始的#个数决定标题层次。你也可以选择用若干个#结束标题行:

# This is an H1 #

## This is an H2 ##

### This is an H3 ######

块引用

> 开始被引用的段落:

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

块引用中可以有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");

列表

无序列表用*+-标记项目:

*   Red
*   Green
*   Blue

相当于

+   Red
+   Green
+   Blue

或者

-   Red
-   Green
-   Blue

有序列表的项目用数字后接.标记:

1.  Bird
2.  McHale
3.  Parish

其中数字是不重要的:

1.  Bird
1.  McHale
1.  Parish

或者

3. Bird
1. McHale
8. Parish

都是生成:

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

项目标记前面至多有三个空格。列表项目同样可写成多行,只要缩进如:

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

如用空行分隔列表项目,则项目会用 <p></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>

于是列表项目可以由多段组成,接下来段落首行由四个空格或一个制表符缩进:

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.

或者

*   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 code block:

        <code goes here>

代码块

代码块每行缩进至少四个空格或一个制表符,如:

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>

代码块中内容会按字面解释,<&被转义,不会进一步进行markdown元素处理,只是四个空格或一个制表符的前导缩进被去掉:

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>

分隔线

仅由至少三个*-_和若干空格组成的行会导致<hr />

* * *

***

*****

- - -

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

其它元素

链接

为创建链接,用方括号包围文本,后接用圆括号包围的URL,也可指定说明:

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>

参考文献链接则用两对方括号,如:

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

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

然后在某个地方定义指向:

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

URL也可用尖括号包围:

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

标题可移到下一行并加更多缩进:

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

链接名字可含字母、数字、空格和标点符号,大小写不敏感,如以下两者相同:

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

省略链接名称会用链接文本替代,例如:

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>

参考文献风格的链接通常比较干净。

强调

*_包围的文本分别会被置于元素<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>

如果 *_ 被空格包围,会视为自身。

代码

代码用`包围,如:

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>

代码中<&被自动转义:

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>

图片

图片格式形如:

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

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

也可用参考文献风格:

![Alt text][id]

结合

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

杂项

自动链接

用尖括号包围的URL或邮箱会变成链接:

<http://example.com/>

生成

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

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

以对付笨笨的机器人。

转义

以下字符可用反斜杠转义:

\ ` * _ {} [] () # + - . ! ## 总结
  • markdown赋予一些标点符号特殊的格式化含义,这使很多常用标点符号都要转义,容易出错。
  • markdown的语法相当脆弱,不明显的空格常常影响排版结果。
  • markdown仅用到HTML的很少功能,所以在markdown中还是常常要内嵌html。
  • markdown并没有明显比生成的html短,可读性也见仁见智。
关键词 markdown html 排版