Python Markdown¶

¥Python Markdown¶

Material for MkDocs 支持大量Python Markdown扩展，这也是它在技术写作中如此有吸引力的原因之一。以下列出了所有受支持的扩展，并链接到参考资料中需要启用哪些功能的章节。

¥Material for MkDocs supports a large number of Python Markdown extensions, which is part of what makes it so attractive for technical writing. Following is a list of all supported extensions, linking to the relevant sections of the reference for which features they need to be enabled.

支持的扩展¶

¥Supported extensions¶

缩写¶

¥Abbreviations¶

1.0.0缩写

¥1.0.0 abbr

Abbreviations扩展添加了向元素添加小工具提示的功能，方法是用abbr标签包裹元素。仅支持纯文本（无标记）。通过mkdocs.yml启用此功能：

¥The Abbreviations extension adds the ability to add a small tooltip to an element, by wrapping it with an abbr tag. Only plain text (no markup) is supported. Enable it via mkdocs.yml:

markdown_extensions:
  - abbr

没有可用的配置选项。请参阅使用方法参考：

¥No configuration options are available. See reference for usage:

警告¶

¥Admonition¶

0.1.0警告

¥0.1.0 admonition

Admonition扩展添加了对警告（通常称为标注）的支持，可以使用简单的语法在 Markdown 中定义。通过mkdocs.yml启用它：

¥The Admonition extension adds support for admonitions, more commonly known as call-outs, which can be defined in Markdown by using a simple syntax. Enable it via mkdocs.yml:

markdown_extensions:
  - admonition

没有可用的配置选项。请参阅使用方法参考：

¥No configuration options are available. See reference for usage:

属性列表¶

¥Attribute Lists¶

0.1.0 attr_list

¥0.1.0 attr_list

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

¥The Attribute Lists extension allows to add HTML attributes and CSS classes to almost every Markdown inline- and block-level element with a special syntax. Enable it via mkdocs.yml:

markdown_extensions:
  - attr_list

没有可用的配置选项。请参阅使用方法参考：

¥No configuration options are available. See reference for usage:

定义列表¶

¥Definition Lists¶

1.1.0 def_list

¥1.1.0 def_list

定义列表扩展添加了通过 Markdown 将定义列表（通常称为描述列表- HTML 中的dl ）添加到文档的功能。通过mkdocs.yml启用此功能：

¥The Definition Lists extension adds the ability to add definition lists (more commonly known as description lists – dl in HTML) via Markdown to a document. Enable it via mkdocs.yml:

markdown_extensions:
  - def_list

没有可用的配置选项。请参阅使用方法参考：

¥No configuration options are available. See reference for usage:

使用定义列表
¥Using definition lists

脚注¶

¥Footnotes¶

1.0.0脚注

¥1.0.0 footnotes

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

¥The Footnotes extension allows to define inline footnotes, which are then rendered below all Markdown content of a document. Enable it via mkdocs.yml:

markdown_extensions:
  - footnotes

不支持任何配置选项。请参阅使用方法参考：

¥No configuration options are supported. See reference for usage:

HTML 中的 Markdown¶

¥Markdown in HTML¶

0.1.0 md_in_html

¥0.1.0 md_in_html

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

¥The Markdown in HTML extension allows for writing Markdown inside of HTML, which is useful for wrapping Markdown content with custom elements. Enable it via mkdocs.yml:

markdown_extensions:
  - md_in_html

默认情况下，Markdown 会忽略原始 HTML 块级元素中的任何内容。启用md_in_html扩展后，可以通过在起始标签中添加markdown属性，将原始 HTML 块级元素的内容解析为 Markdown。markdown markdown将从输出中剥离，而所有其他属性将被保留。
¥
By default, Markdown ignores any content within a raw HTML block-level element. With the md_in_html extension enabled, the content of a raw HTML block-level element can be parsed as Markdown by including a markdown attribute on the opening tag. The markdown attribute will be stripped from the output, while all other attributes will be preserved.

没有可用的配置选项。请参阅使用方法参考：

¥By default, Markdown ignores any content within a raw HTML block-level element. With the md_in_html extension enabled, the content of a raw HTML block-level element can be parsed as Markdown by including a markdown attribute on the opening tag. The markdown attribute will be stripped from the output, while all other attributes will be preserved.

目录¶

¥Table of Contents¶

0.1.0目录

¥No configuration options are available. See reference for usage:

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

¥0.1.0 toc

markdown_extensions:
  - toc:
      permalink: true

支持以下配置选项：

¥The Table of Contents extension automatically generates a table of contents from a document, which Material for MkDocs will render as part of the resulting page. Enable it via mkdocs.yml:

title

7.3.5 – 此选项设置右侧导航侧边栏中目录的标题，该标题通常自动来源于mkdocs.yml中设置的网站语言的翻译：

¥The following configuration options are supported:

markdown_extensions:
  - toc:
      title: On this page

permalink

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

¥7.3.5 – This option sets the title of the table of contents in the right navigation sidebar, which is normally automatically sourced from the translations for the site language as set in mkdocs.yml:

¶⚓︎

markdown_extensions:
  - toc:
      permalink: true

markdown_extensions:
  - toc:
      permalink: ⚓︎

permalink_title

永久链接此选项设置锚链接的标题，该标题在鼠标悬停时显示，并由屏幕阅读器读取。出于无障碍考虑，建议将其更改为更易于识别的名称，并表明锚链接指向相应部分本身：

¥false This option adds an anchor link containing the paragraph symbol ¶ or another custom symbol at the end of each headline, exactly like on the page you're currently viewing, which Material for MkDocs will make appear on hover:

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

slugify

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

¥Permanent link This option sets the title of the anchor link which is shown on hover and read by screen readers. For accessibility reasons, it might be beneficial to change it to a more discernable name, stating that the anchor links to the section itself:

UnicodeUnicode, case-sensitive

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定义目录中要包含的层级范围。这对于标题结构复杂的项目文档很有用，可以缩短目录的长度，或者干脆删除目录：

¥toc.slugify This option allows for customization of the slug function. For some languages, the default may not produce good and readable identifiers – consider using another slug function like for example those from Python Markdown Extensions:

Hide levels 4-6Hide table of contents

markdown_extensions:
  - toc:
      toc_depth: 3

markdown_extensions:
  - toc:
      toc_depth: 0

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

¥6 Define the range of levels to be included in the table of contents. This may be useful for project documentation with deeply structured headings to decrease the length of the table of contents, or to remove the table of contents altogether:

表格¶

¥Tables¶

0.1.0表

¥The other configuration options of this extension are not officially supported by Material for MkDocs, which is why they may yield unexpected results. Use them at your own risk.

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

¥0.1.0 tables

markdown_extensions:
  - tables

没有可用的配置选项。请参阅使用方法参考：

¥The Tables extension adds the ability to create tables in Markdown by using a simple syntax. Enable it via mkdocs.yml (albeit it should be enabled by default):

被取代的扩展¶

¥Superseded extensions¶

以下Python Markdown扩展已不再（或可能不再）受支持，因此不建议使用。建议考虑其他替代方案。

¥No configuration options are available. See reference for usage:

围栏代码块¶

¥Fenced Code Blocks¶

0.1.0 fenced_code_blocks

¥The following Python Markdown extensions are not (or might not be) supported anymore, and are therefore not recommended for use. Instead, the alternatives should be considered.

已被SuperFences取代。此扩展可能仍有效，但SuperFences扩展在许多方面更胜一筹，因为它允许任意嵌套，因此值得推荐。

¥0.1.0 fenced_code_blocks

代码Hilite¶

¥CodeHilite¶

0.1.0代码质量

¥Superseded by SuperFences. This extension might still work, but the SuperFences extension is superior in many ways, as it allows for arbitrary nesting, and is therefore recommended.

已被Highlight取代。由于Highlight与其他重要扩展（如SuperFences和InlineHilite ）有更好的集成，因此6.0.0 版中不再支持 CodeHilite 。

¥0.1.0 codehilite