Skip to content

Python Markdown

Material for MkDocs 支持大量的 Python Markdown 扩展，这也是它在技术写作中如此吸引人的原因之一。以下是所有支持的扩展的列表，并链接到相关的参考部分，以便启用所需的功能。

支持的扩展

缩写

1.0.0 abbr

Abbreviations 扩展添加了为元素添加小工具提示的能力，通过用 abbr 标签包裹它。仅支持纯文本（不支持标记）。通过 mkdocs.yml 启用它：

markdown_extensions:
  - abbr

没有可用的配置选项。有关用法，请参见参考：

警告提示

0.1.0 admonition

Admonition 扩展添加了对警告提示的支持，更常见的称为 call-outs，可以通过使用简单的语法在 Markdown 中定义。通过 mkdocs.yml 启用它：

markdown_extensions:
  - admonition

没有可用的配置选项。有关用法，请参见参考：

属性列表

0.1.0 attr_list

Attribute Lists 扩展允许通过特殊语法向几乎每个 Markdown 行内和块级元素添加 HTML 属性和 CSS 类。通过 mkdocs.yml 启用它：

markdown_extensions:
  - attr_list

没有可用的配置选项。有关用法，请参见参考：

定义列表

1.1.0 def_list

Definition Lists 扩展允许通过 Markdown 向文档添加定义列表（更常见的称为 description lists – dl 在 HTML 中）。通过 mkdocs.yml 启用它：

markdown_extensions:
  - def_list

没有可用的配置选项。有关用法，请参见参考：

脚注

1.0.0 footnotes

Footnotes 扩展允许定义行内脚注，这些脚注随后会在文档的所有 Markdown 内容下方呈现。通过 mkdocs.yml 启用它：

markdown_extensions:
  - footnotes

不支持任何配置选项。有关用法，请参见参考：

HTML 中的 Markdown

0.1.0 md_in_html

Markdown in HTML 扩展允许在 HTML 内编写 Markdown，这对于用自定义元素包装 Markdown 内容非常有用。通过 mkdocs.yml 启用它：

markdown_extensions:
  - md_in_html

默认情况下，Markdown 会忽略原始 HTML 块级元素中的任何内容。启用 md_in_html 扩展后，可以通过在开标签上包含 markdown 属性来将原始 HTML 块级元素的内容解析为 Markdown。markdown 属性将在输出中被删除，而所有其他属性将被保留。

没有可用的配置选项。有关用法，请参见参考：

目录

0.1.0 toc

Table of Contents 扩展自动从文档生成目录，Material for MkDocs 将其作为生成页面的一部分呈现。通过 mkdocs.yml 启用它：

markdown_extensions:
  - toc:
      permalink: true

支持以下配置选项：

title

7.3.5 – 此选项设置目录在右侧导航侧边栏中的标题，通常自动从 mkdocs.yml 中设置的 site language 的翻译中获取：

markdown_extensions:
  - toc:
      title: 本页
permalink

false 此选项在每个标题的末尾添加一个包含段落符号 或其他自定义符号的锚链接，正如您当前查看的页面一样，Material for MkDocs 将在悬停时显示：

markdown_extensions:
  - toc:
      permalink: true

markdown_extensions:
  - toc:
      permalink: ⚓︎
permalink_title

Permanent link 此选项设置在悬停时显示的锚链接标题，并被屏幕阅读器读取。出于可访问性原因，可能有必要将其更改为更易于辨识的名称，说明锚链接指向该部分：

markdown_extensions:
  - toc:
      permalink_title: 参考此部分的锚链接
slugify

toc.slugify 此选项允许自定义 slug 函数。对于某些语言，默认可能无法生成良好且可读的标识符 – 考虑使用其他 slug 函数，例如来自 Python Markdown Extensions 的函数：

markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify {}
toc_depth

6 定义要包含在目录中的级别范围。这对于具有深层结构标题的项目文档可能很有用，以减少目录的长度，或完全移除目录：

markdown_extensions:
  - toc:
      toc_depth: 3

markdown_extensions:
  - toc:
      toc_depth: 0

此扩展的其他配置选项未被 Material for MkDocs 正式支持，因此可能会产生意想不到的结果。使用时请自行承担风险。

表格

0.1.0 tables

Tables 扩展通过简单的语法添加了在 Markdown 中创建表格的能力。通过 mkdocs.yml 启用它（尽管默认情况下应该已启用）：

markdown_extensions:
  - tables

没有可用的配置选项。有关用法，请参见参考：

被替代的扩展

以下 Python Markdown 扩展不再支持（或可能不再支持），因此不推荐使用。相反，应该考虑替代方案。

有界代码块

0.1.0 fenced_code_blocks

被 SuperFences 替代。此扩展可能仍然有效，但 SuperFences 扩展在许多方面更为优越，因为它允许任意嵌套，因此推荐使用。

代码高亮

0.1.0 codehilite

被 Highlight 替代。在 6.0.0 中，停止支持 CodeHilite，因为 Highlight 与其他重要扩展（如 SuperFences 和 InlineHilite）的集成更好。