Skip to content

Python Markdown

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

支持的扩展

缩写

缩写支持 · 扩展缩写

缩写扩展增加了通过使用abbr标签包装元素来添加小工具提示的能力。只支持纯文本（无标记）。通过mkdocs.yml启用它：

markdown_extensions:
  - abbr

没有可用的配置选项。参见使用参考：

Admonition

警告支持 · 扩展Admonition

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

markdown_extensions:
  - admonition

没有可用的配置选项。参见使用参考：

属性列表

属性列表支持 · 扩展属性列表

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

markdown_extensions:
  - attr_list

没有可用的配置选项。参见使用参考：

定义列表

定义列表支持 · 扩展定义列表

定义列表扩展增加了通过 Markdown 向文档添加定义列表（更常见的称为描述列表 - 在 HTML 中为dl）的能力。通过mkdocs.yml启用它：

markdown_extensions:
  - def_list

没有可用的配置选项。参见使用参考：

脚注

脚注支持 · 扩展脚注

脚注扩展允许定义内联脚注，然后在文档的所有 Markdown 内容下方渲染。通过mkdocs.yml启用它：

markdown_extensions:
  - footnotes

不支持配置选项。参见使用参考：

Markdown in HTML

Markdown in HTML 支持 · 扩展Markdown in HTML

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

markdown_extensions:
  - md_in_html

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

没有可用的配置选项。参见使用参考：

目录

目录支持 · 扩展目录

目录扩展自动从文档生成目录，Material for MkDocs 将作为结果页面的一部分渲染。通过mkdocs.yml启用它：

markdown_extensions:
  - toc:
      permalink: true

以下配置选项受支持：

title

默认值：自动设置 - 此选项设置右侧导航侧边栏中的目录标题，通常自动从mkdocs.yml中设置的站点语言的翻译中提取：

markdown_extensions:
  - toc:
      title: On this page

permalink

默认值：false - 此选项在每个标题的末尾添加一个包含段落符号或另一个自定义符号的锚链接，就像你当前正在查看的页面一样，Material for MkDocs 将在悬停时显示：

markdown_extensions:
  - toc:
      permalink: true

⚓︎

markdown_extensions:
  - toc:
      permalink: ⚓︎

permalink_title

默认值：Permanent link - 此选项设置在悬停时显示并由屏幕阅读器读取的锚链接的标题。出于可访问性的原因，将其更改为更明显的名称可能有益，表明锚链接到该部分本身：

markdown_extensions:
  - toc:
      permalink_title: Anchor link to this section for reference

slugify

默认值：headerid.slugify - 此选项允许自定义 slug 函数。对于某些语言，默认值可能无法生成好的和可读的标识符 - 考虑使用另一个 slug 函数，例如Python Markdown Extensions中的那些：

Unicode

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

Unicode, case-sensitive

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

toc_depth

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

隐藏 4-6 级

markdown_extensions:
  - toc:
      toc_depth: 3

隐藏目录

markdown_extensions:
  - toc:
      toc_depth: 0

此扩展的其他配置选项不受 Material for MkDocs 的官方支持，因此可能会产生意外的结果。使用它们需自行承担风险。

表格

表格支持 · 扩展表格

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

markdown_extensions:
  - tables

没有可用的配置选项。参见使用参考：

被取代的扩展

以下Python Markdown扩展可能不再受支持，因此不建议使用。相反，应考虑使用替代方案。

Fenced Code Blocks

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

CodeHilite

被Highlight取代。在 6.0.0 版本中，停止对 CodeHilite 的支持，因为Highlight与SuperFences和InlineHilite等其他必要扩展的集成更好。