扩展 Markdown 语法

声明：本文采用 CC BY-NC-SA 2.5 协议授权，转载请注明本文链接。

本文说明 Python-Markdown¹ 支持的扩展 Markdown² 语法。

支持语法高亮的代码区块

支持多种语言，比如 python, c, html 等。

```python
def hello():
    return 'Hello World'
```

产生如下结果：

def hello():
    return 'Hello World'

Attribute Lists / 属性列表³

定义 HTML 元素的属性。基本语法参照 Maruku's Attribute List。

The List

一个 attribute list 的例子如下所示：

{: #someid .someclass somekey='some values' }

• A word which starts with a hash # will set the id of an element. 以井号 # 开头的单词将设置元素的 id。
• A word which starts with a dot . will add to the list of classes assigned to an element. 以点 . 开头的单词将添加到元素的类列表中。
• A key/value pair will assign that pair to the element. 一个键/值对将赋予元素。

Be aware that while the dot syntax will add to a class, using key/value pairs will always override the previously defined attribute. 注意使用键/值对会覆盖前面的 . 定义类名。比如以下情况：

{: #id1 .class1 id=id2 class="class2 class3" .class4 }

上面的例子会生成如下结果：

id="id2" class="class2 class3 class4"

Block Level

To define attributes for a block level element, the attribute list should be defined on the last line of the block by itself. 块级元素定义属性，其属性列表必须在块的最后一行定义。

This is a paragraph.
{: #an_id .a_class }

上面的例子生成如下结果：

<p id="an_id" class="a_class">This is a paragraph.</p>

The one exception is headers, as they are only ever allowed on one line. 唯一例外的是标题，因为标题只允许一行。

A setext style header {: #setext}
=================================

### A hash style header ### {: #hash }

上面的例子生成如下结果：

<h1 id="setext">A setext style header</h1>
<h3 id="hash">A hash style header</h3>

Inline

To define attributes on inline elements, the attribute list should be defined immediately after the inline element with no whitespace. 内联元素定义属性，其属性列表必须紧接着内联元素定义，中间不能有空格。

[link](http://example.com){: class="foo bar" title="Some title!" }

上面的例子生成如下结果：

<p><a href="http://example.com" class="foo bar" title="Some title!">link</a></p>

Footnotes / 脚注⁴

脚注是在需要标记脚注文字的后面增加一个方括号，方括号中的内容必须以 ^ 开头，再接着是数字、字符串标记：

Footnotes[^1] have a label[^label] and a definition[^!DEF].

接着，在文件的任意地方，你可以把这个脚注的内容定义出来：

[^1]: This is a footnote
[^label]: A footnote on "label"
[^!DEF]: The definition of a footnote.

脚注内容定义的形式就是前面引用脚注的内容，接着一个冒号，再接着一个以上的空格或制表符，最后是脚注定义的内容。

A footnote definition may contain multiple lines, paragraphs, code blocks, blockquotes and most any other markdown syntax. The additional line simply must be indented at least an additional four spaces. 脚注定义的内容可以包含多行、段落、代码区块、区块引用和大多数其他 markdown 格式的内容。对于多行的内容只需要简单缩进至少4个空格。

[^1]: The first paragraph of the definition.

        Paragraph two of the definition.

        > A blockquote with
        > multiple lines.

                a code block

        A final paragraph.

By default, the footnote definitions are placed at the end of the resulting HTML document. However, you may want the footnotes in another location within the document. Simply place the following text at that location within your markdown document. 默认情况下，脚注内容位于生成的 HTML 文档末尾。但是，你也许想将脚注内容放在文档的其他位置。只需要将如下内容放在需要的 markdown 文档位置即可。

///Footnotes Go Here///

Table of Contents / 目录⁵

Place a marker in the document where you would like the table of contents to appear. Then, a nested list of all the headers in the document will replace the marker. The marker defaults to [TOC]. 在需要目录出现的地方放置一个标记，这样会自动生成一个嵌套的包含所有标题的列表。默认的标记是 [TOC]。

[TOC]

# Header 1

## Header 2

上面 markdown 内容会生成如下 HTML 内容：

<div class="toc">
    <ul>
        <li><a href="#header-1">Header 1</a></li>
            <ul>
                <li><a href="#header-2">Header 2</a></li>
            </ul>
    </ul>
</div>
<h1 id="header-1">Header 1</h1>
<h1 id="header-2">Header 2</h1>

目录跳转的标题 id 是依据标题内容自动生成的，只包含英文、数字、下划线 _ 等。对于全部是中文的标题，自动生成的标题 id 为空，导致无法跳转。可以使用前面的 Attribute Lists 方法，定义标题 id。

Tables / 表格⁶

定义表格的语法参照 PHP Markdown Extra。下面 markdown 内容（摘自前面的 PHP 参考文档）：

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

会生成如下 HTML 内容：

<table>
    <thead>
        <tr>
            <th>First Header</th>
            <th>Second Header</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Content Cell</td>
            <td>Content Cell</td>
        </tr>
        <tr>
            <td>Content Cell</td>
            <td>Content Cell</td>
        </tr>
    </tbody>
</table>

第一行包含列标题，第二行包含位于标题和内容之间的强制性分隔线，接下来的每一行就是表格的内容。列与列之间用竖线 | 分隔。

如果愿意的话，可以在表格每一行的开头和结尾处添加竖线 |，如下所示得到的结果和上面一致：

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

注：表格的每一行至少有一个竖线 |，否则无法正确处理表格。这也就意味着，创建只有一列的表格，必须在每一行的开头或者结尾处添加一个竖线 |，或者都添加。

通过在对应列的分隔线添加冒号 : 可以指定列的对齐方式。冒号 : 在分隔线的左边说明此列左对齐，冒号 : 在分隔线的右边说明此列右对齐，冒号 : 在分隔线的左右两边说明此列居中。比如下面的 Item 列是居中的，Value 列是右对齐：

| Item      | Value |
|:---------:| -----:|
| Computer  | $1600 |
| Phone     |   $12 |
| Pipe      |    $1 |

工具

• Babelmark 2
  用于比较不同 Markdown 实现的输出差别的在线工具。This is a tool for comparing the output of various implementations of John Gruber’s markdown syntax for plain text documents.