Python-Markdown学习笔记

写在前面

按照日常需求，

应该开启的扩展为：

• Fenced Code Blocks
• Tables
• Sane Lists
• SmartyPants

建议开启的扩展为：

• Codehilite
• Footnotes
• Meta-Data
• Table of Contents

Python-Markdown简介

Python-Markdown是John Gruber创造的Markdown语言的Python实现。除了极少的差异外（差别见下文），它几乎完全符合其语法参考。点击查看Markdown语法文档。

特性

除了基本的markdown语法，Python-Markdown还支持以下特性：

• 国际化语言输入(International Input) Python-Markdown 接受 Unicode 支持的任何语言，包括 bi-directional text。实际上测试套件包括用俄语和阿拉伯语写的文件。
• 扩展(Extensions) 支持多种扩展用于改变或扩展基本语法。有开放的extension API供你进行开发。
• 多种输出格式(Output Formats) Python-Markdown 支持以 HTML4、XHTML 和 HTML5 格式输出文档。
• 命令行界面(Command Line Interface) 提供了一个命令行脚本方便你进行 markdown 的转换。

差异

虽然 Python-Markdown 尽量贴合 markdown 的语法规则，但某些规则可以以不同的方式解释，不同的方式实现（相关示例请参阅 Babelmark FAQ）。Python-Markdown中发现的已知和有意义的差异总结如下：

• Middle-Word Emphasis Python-Markdown 默认忽略 Middle-Word Emphasis。换言之，some_long_filename.txt 不会成为 some<em>long</em>filename.txt。如有需要，这个选项可以关闭。
• Indentation/Tab Length markdown语法 明确指出，当列表项包含多个段落时：

each subsequent paragraph in a list item must be indented by either 4 spaces or one tab

然而许多markdown语法的实现并不执行此规则，允许缩进少于4个空格。Python-Markdown开发者认为这么做是个bug。

这适用于嵌套在列表中的任何块级元素，包括段落，子列表，块引用，代码块等。对于每个级别的嵌套，必须始终缩进四个空格或一个tab。

• Consecutive Lists 虽然语法规则没有明确指出，但是当列表标记（星号，粗线，连字符和数字）更改时，许多实现（包括原始）不会结束一个列表并启动第二个列表。为了保持一致性，Python-Markdown保持相同的行为，目前没有更改的计划。

安装

1

pip install markdown

或者

1

easy_install markdown

使用参考

简单的

1
2

import markdown
html = markdown.markdown(your_text_string)

详细的

Python-Markdown提供了两个公共函数（markdown.markdown和markdown.markdownFromFile），它们都包含公共类markdown.Markdown。如果您一次处理一个文档，这些功能将满足您的需求。但是，如果您需要处理多个文档，那么创建markdown.Markdown该类的单个实例并通过它传递多个文档可能是有利的。如果您确实使用单个实例，请确保正确调用该reset 方法。

markdown.markdown (text [, **kwargs])

• text（必需）：源Unicode字符串。Python-Markdown期望Unicode作为输入（尽管一些简单的ASCII字符串可能正常工作），并返回输出为Unicode。不要将编码后的字符串传递给它！
• extensions：扩展列表。Python-Markdown为第三方提供了一个API来为解析器编写extension，对语法进行添加或更改。一些常用的extension程序随着markdown库一起提供。有关可用extension的列表，请参阅文档。 extension列表可以包含extension实例或者extension名字符串。优先传extension实例。

1

extensions=[MyExtension(), 'path.to.my.ext']

• extension_configs：扩展名的配置字典。任何配置项只会传递给使用名称字符串加载的extension，使用类实例加载的extension将会在类初始化时直接传递参数。（优选的方法是使用类实例加载extension，因此并不需要使用extension_configs关键字。） 配置字典必须采用以下格式（查看extension的配置参数请参阅extension相关文档）：

1
2
3
4
5
6
7
8
9

extension_configs = {
    'extension_name_1': {
        'option_1': 'value_1',
        'option_2': 'value_2'
    },
    'extension_name_2': {
        'option_1': 'value_1'
    }
}

• output_format：输出格式。支持的格式有（值可以是小写或大写）：

  • "xhtml1"：输出XHTML 1.x. 默认。
  • "xhtml5"：输出HTML 5的XHTML样式标签。
  • "xhtml"：（不推荐使用）输出最新支持的XHTML版本（目前为XHTML 1.1）。
  • "html4"：输出HTML 4。
  • "html5"：输出HTML 5的HTML样式标签
  • "html"：（不推荐使用）输出最新支持的HTML版本（目前为HTML 4）。

• safe_mode：（已被弃用）禁止部分原生HTML标签。默认值：False，可选值 replace、remove、escape。“safe_mode” 也会更改 enable_attributes 选项的默认值。该设置项已被弃用，建议使用HTML清理器（如 Bleach）处理用户提交的不受信任的HTML。

1
2
3

import markdown
import bleach
html = bleach.clean(markdown.markdown(untrusted_text))

• html_replacement_text:当safe_mode设置为replace时用于替换的文本。已被弃用。
• tab_length：tab的长度。默认值：4
• enable_attributes：启用属性的转换。默认为 True，除非 safe_mode 启用，在这种情况下是默认值 False。safe_mode仅覆盖默认值。如果enable_attributes 显式设置，则使用显式值，无论如何safe_mode。但是，这可能会让不受信任的用户将JavaScript注入到文档中。
• smart_emphasis：_connected_words_ 智能处理默认值：True，即上文差异中说的第一点。
• lazy_ol：忽略有序列表的第一个项目的数量。默认值：True，即上文差异中说的第三点。如果设置为False，则给出以下列表：

1
2
3

4. Apples
5. Oranges
6. Pears

将输出：

1
2
3
4
5

<ol start="4">
    <li>Apples</li>
    <li>Oranges</li>
    <li>Pears</li>
</ol>

markdown.markdownFromFile (**kwargs)

除了极少数的情况，markdown.markdownFromFile接受与markdown.markdown相同的参数。但是其不接受text（或Unicode）类型字符串，而是接受以下必传参数：

• input （必填）：源文本文件。

  可以设置为以下三种：

  • 一个字符串，指定了文件系统中可读文件的路径；
  • 一个可读的file-like对象；
  • None（默认），此时将从stdin中读取；

• output：定义输出位置。

  可以设置为以下三种：

  • 一个字符串，指定了文件系统中可写文件的路径；
  • 一个可写的file-like对象；
  • None（默认），此时输出到stdout；

• encoding：源文本文件的编码。默认值是utf-8。输入和输出总是使用相同的编码。编码output时将会使用xmlcharrefreplace错误处理程序。

  这是唯一可以在Python-Markdown中进行Unicode解码和编码的地方。如果这种天真的解决方案不能满足您的具体需求，建议您编写自己的代码来处理编码/解码需求。

markdown.Markdown ([**kwargs])

初始化markdown.Markdown类时，可以使用与markdown.markdown函数相同的参数，唯一的例外是该类在初始化时不接受源文本字符串。源文本字符串必须传递给以下两个实例方法之一：

• Markdown.convert(source)

  该source文本与markdown.markdown函数的text参数有相同的要求。

  你还可以用该方法处理多个字符串而不必为每个字符串创建一个新的类实例。

1
2
3

md = markdown.Markdown()
html1 = md.convert(text1)
html2 = md.convert(text2)

根据要使用的选项和扩展，解析器可能要在每个调用convert方法之间进行复位（reset），否则可能会影响性能：

1
2
3

html1 = md.convert(text1)
md.reset()
html2 = md.convert(text2)

你也可以同时调用reset方法和convert方法：

1

html3 = md.reset().convert(text3)

• Markdown.convertFile(**kwargs)

  该方法的参数与markdown.markdownFromFile函数相同。与convert方法一样，该方法也用于处理多个文件而不必为每个文件创建一个新的类实例，也可在调用convertFile之间调用reset方法。

CLI命令

虽然Python-Markdown主要是一个Python库，但也包括一个命令行脚本。虽然还有许多其他的命令行的Markdown实现，但您可能没有安装它们，或者您更喜欢使用Python-Markdown的各种扩展：）

Python-Markdown的命令行脚本利用了Python的-m标志。因此可以通过以下方式来运行：

1

$ python -m markdown [options] [args]

最基本的用法是只传递一个文件名作为唯一的参数：

1

$ python -m markdown input_file.txt

支持管道输入和输出（STDIN和STDOUT)。例如：

1

$ echo "Some **Markdown** text." | python -m markdown > output.html

使用--help参数查看所有可用选项和参数列表。

1

$ python -m markdown --help

如果不想直接调用Python可执行文件（使用-m标志），请按照以下说明使用封装后的脚本：

设置

Python-Markdown使用"markdown_py"作为脚本名称，因为Perl语言已经使用了更加明显的名称"markdown"。此外，某些系统上的默认Python配置会导致命名为"markdown.py"的脚本不能正常工作，因为系统错误地导入了脚本本身而不是markdown库。因此，我们将脚本命名为了"markdown_py"，如果您希望在您的系统中使用不同的脚本名称，建议您使用软链接指定到markdown_py命令。

使用说明

最简单的方式

1

$ markdown_py input_file.txt

或者

1

$ markdown_py input_file.txt > output_file.html

要查看所有可用选项的列表

1

$ markdown_py --help

加载extension

要从命令行加载Python-Markdown extension，请使用-x （或--extension）选项。扩展模块必须位于您的PYTHONPATH 环境变量中（有关详细信息，请参阅Extension API）。可以使用Python的点语法通过该模块的名称来调用extension：

1

$ python -m markdown -x path.to.module input.txt

要加载多个extension，请为每个extension都指定-x选项：

1

$ python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.codehilite input.txt

如果extension支持配置选项，您也可以将它们传入：

1

$ python -m markdown -x markdown.extensions.footnotes -c config.yml input.txt

该-c（或--extension_configs）选项接受一个文件名。该文件必须是YAML或JSON格式，并且包含YAML或JSON格式的内容，储存markdown.Markdown的extension_configs关键字参数使用的dict。因此，config.yaml上述示例中引用的文件可能如下所示：

1
2
3

markdown.extensions.footnotes:
    PLACE_MARKER: ~~~~~~~~
    UNIQUE_IDS: True

请注意，虽然该--extension_configs选项确实指定了“markdown.extensions.footnotes” extension，但您仍然需要使用-x选项加载该extension，否则该extension的配置将被忽略。

如果您的系统中安装了PyYAML，--extension_configs选项将能够支持YAML格式配置文件。JSON格式配置文件的支持不需要安装额外扩展。程序会自动检测配置文件的格式。

官方Extensions

下面列出的extensions都包含在最新版本的Python-Markdown包中，并且由Python-Markdown官方维护。

Extra

这是一部分Python-Markdown扩展的集合，主要模仿了PHP Markdown Extra。

Abbreviations

该扩展提供定义缩写的功能。任何定义的缩写都会被包含在<abbr>标签中。

举例说明，下面的文本

1
2
3
4
5

The HTML specification
is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium

将会被解析为：

1
2
3
4
5
6
7

<p>
    The
    <abbr title="Hyper Text Markup Language">HTML</abbr>
    specification is maintained by the
    <abbr title="World Wide Web Consortium">W3C</abbr>
    .
</p>

Attribute Lists

该扩展为HTML输出中的元素添加了属性定义。

语法

属性列表定义如下所示：

1

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

以hash（#）开头的单词将设置为一个元素的id，以dot（.）开头的单词将被添加到元素的class中，键值对（somekey='some value'）将会作为属性分配给元素。注意，对于class，后定义的键值对会覆盖前定义的dot语法。

例如，下面的定义：

1

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

其属性定义的结果是：

1

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

使用

• 定义块级元素的属性，属性列表应该在块的最后一行定义。

1
2

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

以上的解析结果是：

1

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

对于标题，只能定义在同一行：

1
2
3
4

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

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

以上的解析结果是：

1
2

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

• 定义内联元素的属性，属性应在同一行的内联元素后定义，且中间不能有空格。

1

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

以上的解析结果是：

1

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

Definition Lists

该扩展用于定义HTML中的definition list。

1
2
3
4
5
6

Apple
:   Pomaceous fruit of plants of the genus Malus in
    the family Rosaceae.

Orange
:   The fruit of an evergreen tree of the genus Citrus.

将呈现为：

1
2
3
4
5
6
7
8

<dl>
<dt>Apple</dt>
<dd>Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.</dd>

<dt>Orange</dt>
<dd>The fruit of an evergreen tree of the genus Citrus.</dd>
</dl>

Fenced Code Blocks

该扩展用于定义多行代码块。

可以这样：

1
2
3
4
5
6
7

​~~~~{.python}
# python code
​~~~~

​~~~~.html
<p>HTML Document</p>
​~~~~

或者这样

1
2
3

​```python
# more python code
​```

对代码块中某些行进行强调（需要安装 Pygments依赖）：

1
2
3
4
5

​~~~~{.python hl_lines="1 3"}
# This line is emphasized
# This line isn't
# This line is emphasized
​~~~~

或者

1
2
3
4
5

​```python hl_lines="1 3"
# This line is emphasized
# This line isn't
# This line is emphasized
​```

Footnotes

该扩展支持在Markdown文档中定义脚注。

1
2
3
4

Footnotes[^1] have a label[^@#$%] and the footnote's content.

[^1]: This is a footnote content.
[^@#$%]: A footnote on the label: "@#$%".

脚注标签定义在一组square brackets（[]）中，必须以caret（^）开头，标签名中可能包含任何内联文本，包括空格。只有第一个^是有特殊含义的。

脚注内容格式：在标签后必须跟冒号和至少一个空格，然后在同一行或者下一行添加脚注内容。内容可以包含多行、段落、代码块、引用和其他大多数markdown语法。从第二行开始应当缩进一级（四个空格或者一个tab）。

当使用多个块时，建议在块与块之间空一行分割内容，增加可读性。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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

    Paragraph two of the definition.

    > A blockquote with
    > multiple lines.

        a code block

    A final paragraph.

Tables

该扩展支持在Markdown文档中定义表格。

1
2
3
4

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

将呈现为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

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

Smart_Strong

该扩展能智能处理双下划线标识的强调。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

>>> import markdown
>>> markdown.markdown('Text with double__underscore__words.', \
                      extensions=['markdown.extensions.smart_strong'])
u'<p>Text with double__underscore__words.</p>'
>>> markdown.markdown('__Strong__ still works.', \
                      extensions=['markdown.extensions.smart_strong'])
u'<p><strong>Strong</strong> still works.</p>'
>>> markdown.markdown('__this__works__too__.', \
                      extensions=['markdown.extensions.smart_strong'])
u'<p><strong>this__works__too</strong>.</p>'

Admonition

该扩展支持在markdown中定义rST-style admonitions。

1
2
3
4

!!! type "optional explicit title within double quotes"
    Any number of other indented markdown elements.

    This is the second paragraph.

如果没有标题，type将被用作css类名和默认标题。rST建议以下内容的type：attention, caution, danger, error, hint, important, note, tip, warning。举个🌰：

1
2

!!! note
    You should note that the title will be automatically capitalized.

1
2
3
4

<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You should note that the title will be automatically capitalized.</p>
</div>

如果不想有标题，可以将标题设置为空字符串""

1
2

!!! important ""
    This is a admonition box without a title.

1
2
3

<div class="admonition important">
<p>This is a admonition box without a title.</p>
</div>

CodeHilite

安装

该扩展使用 Pygments 为代码块添加语法高亮。使用该插件需要先安装 Pygments：

1

pip3 install pygments

通过 Pygments 生成 css 样式文件：

1

pygmentize -S default -f html -a .codehilite > styles.css

-S 指定使用的 css 主题样式名称，Pygments 内置了多种主题，查看内置主题列表：

1

pygmentize -L style

下面的网站提供了主题的预览：

• Pygments Syntax Highlighter CSS Theme Files
• pygments-css by richleland

-a 选项应与 codehilete 的配置 css_class 保持一致。

把生成的 css 文件集成到展示 markdown 文档的 html 中，即可实现代码块语法高亮。

配置

该扩展有以下配置项：

• linenums 是否展示行号。默认为 None 表示自动处理，可以设置为 True - 展示，False - 不展示。
• guess_lang 猜测代码块语言。默认为 True，可以设置为 False。
• css_class 设置代码块 div 标签中的 css类名，默认为 codehilite。
• pygments_style Pygment HTML 主题样式名称，默认为 default。该选项只在 noclasses 为 True 时有效，否则应该另外提供 css 文件。
• noclasses 使用内联样式，默认为 False。
• use_pygments 使用 Pygment，默认为 True。

Headerld

该扩展自动为生成的HTML文件中的标题元素（h1-h6)生成id属性。

注意：该扩展即将被弃用，请使用提供了更多特性的TOC扩展作为替代。

语法

默认情况下，将会基于标题的文本生成唯一的标题id。举🌰如下：

1
2
3

# Header
# Header
# Header

渲染结果是：

1
2
3

<h1 id="header">Header</h1>
<h1 id="header_1">Header</h1>
<h1 id="header_2">Header</h1>

使用

选项如下：

• level：设置标题的基本级别，默认值为1。假如你要设置所有的标题都不高于level 3(<h3>)：

1
2
3
4
5
6
7
8

>>>  text = '''
... #Some Header
... ## Next Level'''
>>> from markdown.extensions.headerid import HeaderIdExtension
>>> html = markdown.markdown(text, extensions=[HeaderIdExtension(level=3)])
>>> print html
<h3 id="some_header">Some Header</h3>
<h4 id="next_level">Next Level</h4>'

• fouceid：强制所有headers都有id，默认值True。

1
2
3
4
5
6
7
8
9

>>> text = '''
... # Some Header
... # Header with ID # { #foo }'''
>>> html = markdown.markdown(text,
                           extensions=['markdown.extensions.attr_list',
                                       HeaderIdExtension(forceid=False)])
>>> print(html)
<h1>Some Header</h1>
<h1 id="foo">Header with ID</h1>

• separator：单词分隔符，用于代替id中的空格。默认值-。

• slugify：用于生成锚点。默认值markdown.extensions.headerid.slugify。如果你想使用不同的id生成算法，你可以传一个包含以下两个参数的可调用对象：

  • value：slugify字符串。
  • separator：单词分隔符。

使用Meta-data

该扩展支持Meta-data扩展。使用的关键字是：

• header_level
• header_forceid

使用时，meta-data将会覆盖通过extension_configs接口传入的设置。

1
2
3
4

header_level: 2
header_forceid: Off

# A Header

渲染后：

1

<h2>A Header</h2>

Meta-Data

该扩展提供了定义文档元数据的方法。目前，该扩展并不使用元数据，而是作为Markdown实例的 Meta 属性，供其他扩展或直接被 Python 代码调用。

Syntax

Meta-data 定义在 markdown 文件的开头，包含一系列的 keyword 和 value。keyword 不区分大小写，可能包含字母、数字、下划线和短横线，必须以冒号结尾。value 包含冒号后当前行的所有内容，也可为空。

如果一行缩进不少于 4 个空格，这一行被认为是先前行 keyword 的 value 的附加行，可以有多行 keyword。

空行将会结束所有 Meta-data 的定义。因此，如果含有元数据定义，文档的第一行不能是空行。

1
2
3
4
5
6
7
8
9

Title:   My Document
Summary: A brief description of my document.
Authors: Waylan Limberg
         John Doe
Date:    October 2, 2007
blank-value:
base_url: http://example.com

This is the first paragraph of the document.

你也可以使用 YAML 样式来标识 Meta-data 的起止行。此时，文档的第一行必须是 —--，Meta-data 在遇到第一个空白行结束，或遇到包含结尾分隔符（--- 或者 ...）的行结束。如此做的话，即使 Markdown 支持 YAML 解析，元数据也不会被解析为 YAML 内容。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
Title:   My Document
Summary: A brief description of my document.
Authors: Waylan Limberg
         John Doe
Date:    October 2, 2007
blank-value:
base_url: http://example.com
---

This is the first paragraph of the document.

上面两个例子的解析结果：

1

"<p>This is the first paragraph of the document.</p>"

访问Meta-data

meta-data 在 Markdown 类实例的 Meta 属性中作为一个 python Dict 提供。注意：所有的 keyword 都是小写的，value 是一个 String 组成的 List，其中的每一个元素是该 keyword 的一行，不包含换行符。如果有需要，可以保留换行符或者在合适的时候加上。

1
2
3
4
5
6
7
8

{
    'authors': ['Waylan Limberg', 'John Doe'],
    'base_url': ['http://example.com'],
    'blank-value': [''],
    'date': ['October 2, 2007'],
    'summary': ['A brief description of my document.'],
    'title': ['My Document']
}

元数据可以在模版系统中传入，或者被其他Markdown扩展使用。只有你想不到哈哈哈～

已兼容的扩展

• HeaderId
  • header_level
  • header_forceid
• WikiLinks
  • wiki_base_url
  • wiki_end_url
  • wiki_html_class

New Line to Break

该扩展(nl2br)会把markdown中的换行视为”hard break“，类似StackOverFlow和GitHub的风格。

1
2
3
4
5
6
7
8
9

>>> import markdown
>>> text = """
... Line 1
... Line 2
... """
>>> html = markdown.markdown(text, extensions=['markdown.extensions.nl2br'])
>>> print html
<p>Line 1<br />
Line 2</p>

Sane Lists

该扩展改变了Markdown中列表的语法。

Sane List不允许列表项混合。即当遇到无序列表时，有序列表将不会继续，反之亦然。例如：

1
2
3
4
5

1. Ordered item 1
2. Ordered item 2

* Unordered item 1
* Unordered item 2

将产生以下输出：

1
2
3
4
5
6
7
8
9

<ol>
  <li>Ordered item 1</li>
  <li>Ordered item 2</li>
</ol>

<ul>
  <li>Unordered item 1</li>
  <li>Unordered item 2</li>
</ul>

而默认的Markdown行为是生成有序列表（实测）。

注意，与默认的Markdown行为不同，如果列表项之间未包含空白行，不同的列表类型将被忽略，这与段落的行为一致。

1
2
3
4
5

A Paragraph.
* Not a list item.

1. Ordered list item.
* Not a separate list item.

该扩展的输出为：

1
2
3
4
5
6
7

<p>A Paragraph.
* Not a list item.</p>

<ol>
  <li>Ordered list item.
  * Not a separate list item.</li>
</ol>

默认Markdown输出：

1
2
3
4
5
6
7

<p>A Paragraph.
* Not a list item.</p>

<ol>
<li>Ordered list item.</li>
<li>Not a separate list item.</li>
</ol>

在其他方面，该扩展与正常的Markdown列表一致。

SmartyPants

该扩展将ASCII码的短横线dash、引号quotes、和省略号ellipses替换为他们的html表示法。

使用’substitutions’配置项你可以覆盖默认配置。只需要传一个dict映射key和替代的string。

举个🌰

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

extension_configs = {
    'markdown.extensions.smarty': {
        'substitutions': {
            'left-single-quote': '‚', # sb is not a typo!
            'right-single-quote': '‘',
            'left-double-quote': '„',
            'right-double-quote': '“'
        }
    }
}

扩展配置项：

Table of Contents

该扩展用于生成目录。

Syntax

使用扩展时默认情况下，所有标题将自动基于标题文本生成唯一的标题id属性，像HeaderId扩展一样。

在文档需要放置目录的地方放一个[TOC]标记，将会替换为由所有标题生成的嵌套列表。

无论在文档中有没有maker（默认是[TOC]），都可以使用Markdown类实例的toc属性读取目录内容，然后在页面模版中使用目录。

Usage

提供以下选项来配置输出：

• maker：在文档中用于寻找和替换目录的字符串，默认值是[TOC]。设置为空字符串将会禁用搜索maker，这在长文档中能够节约转换的时间。

• title：插入目录<div>元素的title，默认值为None。

• anchorlink：设置为True将使所有标题链接到自己。默认值为False。

• permalink：设置为True或一个String，以在每个标题的末尾生成永久链接。适用于Sphinx样式表。当设置为True时，段落符号（¶或 ¶）用作链接文本；当设置为String时，提供的String作为链接文本。

• baselevel：标题的基本级别，默认为1。举个例子，假如设置为3，那么所有标题的级别都不会高于3，如下：

1
2
3
4
5
6
7
8

>>>  text = '''
... #Some Header
... ## Next Level'''
>>> from markdown.extensions.toc import TocExtension
>>> html = markdown.markdown(text, extensions=[TocExtension(baselevel=3)])
>>> print html
<h3 id="some_header">Some Header</h3>
<h4 id="next_level">Next Level</h4>'

• slugify：用于生成锚点，默认值markdown.extensions.headerid.slugify。与HeaderId的slugify参数用法相同。
• separator：单词分隔符，用于替换id中的空格，默认值是-。

WikiLinks

该扩展提供了对WikiLinks的支持。具体来说，任何的[[bracketed]]标记都将转换为链接。

Syntax

[[bracketed]]标记由大写字母、小写字母、数字、短横线dash、下划线和空格组成，被两个方括号包裹而成。WikiLinks会自动分配class="wikilink"属性以使WikiLink的样式与页面上其他链接进行区别。下面会降到如何修改class名。因此：

1

[[Bracketed]]

将会被转换为：

1

<a href="/Bracketed/" class="wikilink">Bracketed</a>

注意，如果标记中含有空格，将会在链接中被转换为下划线，但在文本中保留原样。举个🌰：

1

[[Wiki Link]]

会转换为：

1

<a href="/Wiki_Link/" class="wikilink">Wiki Link</a>

Usage

默认情况下，链接将会指向域名的根目录，并使用尾部斜线关闭。此外，每个链接都分配了CSS class wikilink。

配置项如下：

• base_url：添加到URL开头的字符串，默认值/。
• end_url：添加到URL末尾的字符串，默认值/。
• html_class：CSS类名，留空为None，默认值wikilink。
• build_url：可调用对象，用于格式化URL，传入三个参数（label， base，和end），返回URL。

Examples

使链接始终指向/wiki/的子目录并以.html结尾：

1
2
3
4

>>> from markdown.extensions.wikilinks import WikiLinkExtension
>>> html = markdown.markdown(text,
...     extensions=[WikiLinkExtension(base_url='/wiki/', end_url='.html')]
... )

将会使[[WikiLink]]变为：

1

<a href="/wiki/WikiLink.html" class="wikilink">WikiLink</a>

如果你想要的不只是改变url的开头和结尾，可以使用build_url：

1
2
3
4
5
6
7

>>> def my_url_builder(label, base, end):
...    # do stuff
...    return url
...
>>> html = markdown.markdown(text,
...     extensions=[WikiLinkExtension(build_url=my_url_builder)],
... )

使用Meta-Data扩展

支持使用的meta-data关键字是：

• wiki_base_url
• wiki_end_url
• wiki_html_class

使用时，meta-data将覆盖通过extension_configs提供的设置。

如下的markdown文件：

1
2
3
4
5

wiki_base_url: http://example.com/
wiki_end_url:  .html
wiki_html_class:

A [[WikiLink]] in the first paragraph.

将会导致以下输出（注意wiki_html_class是空白的）：

1

<p>A <a href="http://example.com/WikiLink.html">WikiLink</a> in the first paragraph.</p>

第三方Extensions

这有个第三方扩展的列表——Third Party Extensions

Extension API

放个链接，暂时用不上。https://pythonhosted.org/Markdown/extensions/api.html