markdown

2015-02-26 本文已影响392人 yesuu

概述

宗旨

Markdown 的目标是「易读易写」。

兼容 HTML

HTML 是一种发布的格式，Markdown 是一种书写的格式。

你可以直接在 Markdown 文档里面写 HTML 。不需要额外标注这是 HTML 或是 Markdown 。

例子如下，在 Markdown 文件里加上一段 HTML 表格：

这是一个普通段落。

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

这是另一个普通段落。

限制规则：

一些 HTML 区块元素――比如 <div>、<table>、<pre>、<p> 等标签，必须在前后加上空行与其它内容区隔开，还要求它们的开始标签与结尾标签不能用制表符或空格来缩进。(Markdown 的生成器有足够智能，不会在 HTML 区块标签外加上不必要的 <p> 标签。)
在 HTML 区块标签间的 Markdown 格式语法将不会被处理。比如，你在 HTML 区块内使用 Markdown 样式的强调会没有效果。
HTML 的区段（行内）标签如 <span>、<cite>、<del> 可以在 Markdown 的段落、列表或是标题里随意使用。(照个人习惯，甚至可以不用 Markdown 格式，而直接采用 HTML 标签来格式化。举例说明：如果比较喜欢 HTML 的 <a> 或 <img> 标签，可以直接使用这些标签，而不用 Markdown 提供的链接或是图像标签语法。)
和处在 HTML 区块标签间不同，Markdown 语法在 HTML 区段标签间是有效的。

特殊字符自动转义

编写 HTML 的时候免不了要使用&来转义，在 Markdown 里可以对这些东西自动转义。

比如写&的时候，Markdown会把它自动转换为&，
但如果你写©，它就会原封不动的输出©，
Markdown果然够机智！

如果你是把 < 符号作为 HTML 标签的定界符使用，Markdown 不会傻到转换它。
但是如果你写4 < 5，Markdown 会把它转换为4 < 5。

在 code 范围内，Markdown 会对所有字符转义。

区块元素

段落和换行

一个 Markdown 段落是由一个或多个连续的文本行组成，它的前后要有一个以上的空行（空行的定义是显示上看起来像是空的，便会被视为空行。比方说，若某一行只包含空格和制表符，则该行也会被视为空行）。普通段落不该用空格或制表符来缩进。

「由一个或多个连续的文本行组成」这句话其实暗示了 Markdown 允许段落内的强迫换行（插入换行符）

如果你确实想要依赖 Markdown 来插入 <br /> 标签的话，在插入处先按入两个以上的空格然后回车。

标题

Markdown 支持两种标题的语法，类 Setext 和类 atx 形式。

类 Setext 形式是用底线的形式，利用 = （最高阶标题）和 - （第二阶标题），例如：

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

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

任何数量的 = 和 - 都可以有效果。

类 Atx 形式则是在行首插入 1 到 6 个 # ，对应到标题 1 到 6 阶，例如：

# 这是 H1

## 这是 H2

###### 这是 H6

你可以选择性地「闭合」类 atx 样式的标题，这纯粹只是美观用的，若是觉得这样看起来比较舒适，你就可以在行尾加上 #，而行尾的 # 数量也不用和开头一样（行首的井字符数量决定标题的阶数）：

# 这是 H1 #

## 这是 H2 ##

### 这是 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.

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 语法，包括标题、列表、代码区块等：

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

代码区块

和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块，通常这些区块我们并不希望它以一般段落文件的方式去排版，而是照原来的样子显示，Markdown 会用 <pre> 和 <code> 标签来把代码区块包起来。

要在 Markdown 中建立代码区块很简单，只要简单地缩进 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 实体，这样的方式让你非常容易使用 Markdown 插入范例用的 HTML 原始码，只需要复制贴上，再加上缩进就可以了，剩下的 Markdown 都会帮你处理，例如：

    <div class="footer">
        © 2004 Foo Corporation
    </div>

会被转换为：

<pre><code><div class="footer">
    © 2004 Foo Corporation
</div>
</code></pre>

代码区块中，一般的 Markdown 语法不会被转换，像是星号便只是星号，这表示你可以很容易地以 Markdown 语法撰写 Markdown 语法相关的文件。

列表

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 输出。

如果你使用懒惰的写法，建议第一个项目最好还是从 1. 开始，因为 Markdown 未来可能会支持有序列表的 start 属性。

你可以使用缩进也可以不用，最终效果是一样的，比如：

*   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 时 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 个空格或是 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.

如果要在列表项目内放进引用，那 > 就需要缩进：

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

如果要放代码区块的话，该区块就需要缩进两次，也就是 8 个空格或是 2 个制表符：

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

        <代码写在这>

有的时候你会需要转义：

1986\. What a great season.

反斜杠用来转义

区段元素

链接

中括号里是链接字符，小括号里是链接地址，链接地址后面可以跟一个链接提示，就像这样：

[an example](http://example.com/ "Title")

你也使用相对路径：

[About](/about)

链接还有第二种写法（建议，因为写起来比较好看）：

[an example][id]

[an example] [id]

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

两个中括号之间可以有个空格，冒号后面要有个空格或者制表符。

下面的写法都是对的：

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)
[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" 链接到 google.com，你可以简化成：

[Google][]

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

由于链接文字可能包含空白，所以这种简化型的标记内也许包含多个单词：

Visit [Daring Fireball][] for more information.

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

链接的定义可以放在文件中的任何一个地方，我比较偏好直接放在链接出现段落的后面，你也可以把它放在文件最后面。

图片

图片的语法和链接的基本一样，只需要在前面加一个英文叹号：

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

强调

被 * 或 _ 包围的字词会被转成用 <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>

你用什么符号开启标签，就要用什么符号结束。

如果你的 * 和 _ 两边都有空白的话，它们就只会被当成普通的符号

有的时候你需要转义：

\*this text is surrounded by literal asterisks\*

代码

如果要标记一小段行内代码，你可以用反引号把它包起来（`），例如：

Use the `printf()` function.

如果要在代码区段内插入反引号，你可以用多个反引号来开启和结束代码区段：

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

其他

自动链接

就像这样：

<http://example.com/>

会转为：

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

电子邮件地址的处理方法和链接基本一样，只是会对地址进行编码，可能会抵挡一些爬虫：

<address@example.com>

会转成：

<a href="mailto:addre
ss@example.co
m">address@exa
mple.com</a>

在浏览器里面，这段字串（其实是 <a href="mailto:address@example.com">address@example.com</a>）会变成一个可以点击的「address@example.com」链接。

反斜杠

反斜杠用来转义，比如：

\*literal asterisks\*

转义的方法是反斜杠后跟下面这些字符：

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

markdown

概述

宗旨

兼容 HTML

特殊字符自动转义

区块元素

段落和换行

标题

分隔线

引用

代码区块

列表

区段元素

链接

图片

强调

代码

其他

自动链接

反斜杠

猜你喜欢

热点阅读