Python Markdown 扩展¶

¥Python Markdown Extensions¶

Python Markdown 扩展包是一个优秀的附加扩展集合，非常适合高级技术写作。Material for MkDocs 将此包列为显式依赖项，因此它会随受支持的版本自动安装。

¥The Python Markdown Extensions package is an excellent collection of additional extensions perfectly suited for advanced technical writing. Material for MkDocs lists this package as an explicit dependency, so it's automatically installed with a supported version.

支持的扩展¶

¥Supported extensions¶

一般来说，所有Python Markdown 扩展都应兼容 Material for MkDocs。以下列表包含所有原生支持的扩展，这意味着它们无需任何进一步调整即可使用。

¥In general, all extensions that are part of Python Markdown Extensions should work with Material for MkDocs. The following list includes all extensions that are natively supported, meaning they work without any further adjustments.

Arithmatex¶

¥Arithmatex¶

1.0.0 pymdownx.arithmatex

¥1.0.0 pymdownx.arithmatex

Arithmatex扩展允许渲染块和内联块方程式，并与MathJax 1 （一个数学排版库）无缝集成。通过mkdocs.yml启用它：

¥The Arithmatex extension allows for rendering of block and inline block equations and integrates seamlessly with MathJax¹ – a library for mathematical typesetting. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

除了在mkdocs.yml中启用扩展之外，还需要包含 MathJax 配置和 JavaScript 运行时，这可以通过几行额外的 JavaScript来完成：

¥Besides enabling the extension in mkdocs.yml, a MathJax configuration and the JavaScript runtime need to be included, which can be done with a few lines of additional JavaScript:

docs/javascripts/mathjax.js mkdocs.yml

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

document$.subscribe(() => { // (1)!
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})

这将 MathJax 与即时加载功能集成在一起
¥This integrates MathJax with instant loading

extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

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

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

使用方法见参考：

¥See reference for usage:

BetterEm¶

¥BetterEm¶

0.1.0 pymdownx.betterem

¥0.1.0 pymdownx.betterem

BetterEm扩展改进了 Markup 的检测功能，可以使用特殊字符（例如**bold**和_italic_ ）来强调 Markdown 中的文本。您可以通过mkdocs.yml启用此功能：

¥The BetterEm extension improves the detection of Markup to emphasize text in Markdown using special characters, i.e. for **bold** and _italic_ formatting. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.betterem

此扩展的配置选项并非特定于 Material for MkDocs，因为它们仅影响 Markdown 解析阶段。有关更多信息，请参阅BetterEm 文档。

¥The configuration options of this extension are not specific to Material for MkDocs, as they only impact the Markdown parsing stage. See the BetterEm documentation for more information.

标题¶

¥Caption¶

1.0.0 pymdownx.blocks.caption

¥1.0.0 pymdownx.blocks.caption

Caption扩展添加了为任何 Markdown 块（包括图像、表格和代码块）添加标题的功能。通过mkdocs.yml启用此功能：

¥The Caption extension adds the ability to add captions to any Markdown block, including images, tables, and code blocks. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.blocks.caption

此扩展的配置选项并非特定于 Material for MkDocs，因为它们仅影响 Markdown 解析阶段。有关更多信息，请参阅Caption 文档。

¥The configuration options of this extension are not specific to Material for MkDocs, as they only impact the Markdown parsing stage. See the Caption documentation for more information.

插入符号、标记和波浪号¶

¥Caret, Mark & Tilde¶

1.0.0 pymdownx.caret

¥1.0.0 pymdownx.caret

Caret 、 Mark和Tilde扩展添加了高亮文本以及使用简单语法定义上下标的功能。可以通过mkdocs.yml同时启用它们：

¥The Caret, Mark and Tilde extensions add the ability to highlight text and define sub- and superscript using a simple syntax. Enable them together via mkdocs.yml:

markdown_extensions:
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde

此扩展的配置选项并非特定于 Material for MkDocs，因为它们仅影响 Markdown 解析阶段。请参阅Caret 、 Mark和Tilde 文档以获取指导。

¥The configuration options of this extension are not specific to Material for MkDocs, as they only impact the Markdown parsing stage. See the Caret, Mark and Tilde documentation for guidance.

使用方法见参考：

¥See reference for usage:

评论家¶

¥Critic¶

1.0.0 pymdownx.critic

¥1.0.0 pymdownx.critic

Critic扩展允许使用Critic Markup高亮显示文档中添加、删除或更新的部分，例如用于跟踪 Markdown 语法的变更。通过mkdocs.yml启用它：

¥The Critic extension allows for the usage of Critic Markup to highlight added, deleted or updated sections in a document, i.e. for tracking changes in Markdown syntax. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.critic

支持以下配置选项：

¥The following configuration options are supported:

mode

view此选项定义如何解析标记，即是否仅view所有建议的更改，或者accept或reject它们：

¥view This option defines how the markup should be parsed, i.e. whether to just view all suggested changes, or alternatively accept or reject them:

View changesAccept changesReject changes

markdown_extensions:
  - pymdownx.critic:
      mode: view

markdown_extensions:
  - pymdownx.critic:
      mode: accept

markdown_extensions:
  - pymdownx.critic:
      mode: reject

使用方法见参考：

¥See reference for usage:

突出显示更改
¥Highlighting changes

细节¶

¥Details¶

1.9.0 pymdownx.details

¥1.9.0 pymdownx.details

Details扩展增强了Admonition扩展的功能，使生成的标注可折叠，方便用户打开和关闭。通过mkdocs.yml启用它：

¥The Details extension supercharges the Admonition extension, making the resulting call-outs collapsible, allowing them to be opened and closed by the user. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.details

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

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

可折叠积木
¥Collapsible blocks

表情符号¶

¥Emoji¶

1.0.0 pymdownx.emoji

¥1.0.0 pymdownx.emoji

Emoji扩展会自动将*.svg文件格式的捆绑图标和自定义图标及表情符号内联到生成的 HTML 页面中。通过mkdocs.yml启用此功能：

¥The Emoji extension automatically inlines bundled and custom icons and emojis in *.svg file format into the resulting HTML page. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji # (1)!
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

Python Markdown Extensions使用pymdownx命名空间，但为了支持图标内联，必须使用materialx命名空间，因为它扩展了pymdownx的功能。
¥Python Markdown Extensions uses the pymdownx namespace, but in order to support the inlining of icons, the materialx namespace must be used, as it extends the functionality of pymdownx.

支持以下配置选项：

¥The following configuration options are supported:

emoji_index

emojione此选项定义使用哪组表情符号进行渲染。请注意，由于许可限制，不建议使用emojione ：

¥emojione This option defines which set of emojis is used for rendering. Note that the use of emojione is not recommended due to restrictions in licensing:

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji

emoji_generator

to_png此选项定义解析后的表情符号或图标短代码的渲染方式。请注意，图标只能与to_svg配置一起使用：

¥to_png This option defines how the resolved emoji or icon shortcode is render. Note that icons can only be used together with the to_svg configuration:

markdown_extensions:
  - pymdownx.emoji:
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

custom_icons

此选项允许列出带有附加图标集的文件夹，以便在 Markdown 或mkdocs.yml中使用，图标自定义指南中有更详细的说明：

¥ This option allows to list folders with additional icon sets to be used in Markdown or mkdocs.yml, which is explained in more detail in the icon customization guide:

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons

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

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

使用方法见参考：

¥See reference for usage:

强调¶

¥Highlight¶

5.0.0 pymdownx.highlight

¥5.0.0 pymdownx.highlight

Highlight扩展新增了对代码块（借助SuperFences ）和内联代码块（借助InlineHilite ）语法高亮的支持。通过mkdocs.yml启用此功能：

¥The Highlight extension adds support for syntax highlighting of code blocks (with the help of SuperFences) and inline code blocks (with the help of InlineHilite). Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences # (1)!

SuperFences扩展使用Highlight对代码块执行语法突出显示，而不是相反，这就是为什么也需要启用此扩展的原因。
¥Highlight is used by the SuperFences extension to perform syntax highlighting on code blocks, not the other way round, which is why this extension also needs to be enabled.

支持以下配置选项：

¥The following configuration options are supported:

use_pygments

true此选项允许控制是否应在构建期间使用Pygments进行突出显示，或者在浏览器中使用 JavaScript 语法突出显示：

¥true This option allows to control whether highlighting should be carried out during build time using Pygments or in the browser with a JavaScript syntax highlighter:

PygmentsJavaScript

markdown_extensions:
  - pymdownx.highlight:
      use_pygments: true
  - pymdownx.superfences

markdown_extensions:
  - pymdownx.highlight:
      use_pygments: false

例如，JavaScript 语法高亮器Highlight.js可以与mkdocs.yml中的一些附加 JavaScript和附加样式表集成：

¥As an example, Highlight.js, a JavaScript syntax highlighter, can be integrated with some additional JavaScript and an additional style sheet in mkdocs.yml:

docs/javascripts/highlight.js mkdocs.yml

document$.subscribe(() => {
  hljs.highlightAll()
})

extra_javascript:
  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
  - javascripts/highlight.js
extra_css:
  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css

请注意， Highlight.js与Highlight扩展没有任何关联。

¥Note that Highlight.js has no affiliation with the Highlight extension.

所有以下配置选项仅与使用Pygments的构建时语法突出显示兼容，因此如果use_pygments设置为false ，则它们不适用。

¥All following configuration options are only compatible with build-time syntax highlighting using Pygments, so they don't apply if use_pygments is set to false.

pygments_lang_class

false此选项指示Pygments添加 CSS 类来识别代码块的语言，这对于自定义注释标记的功能至关重要：

¥false This option instructs Pygments to add a CSS class to identify the language of the code block, which is essential for custom annotation markers to function:

markdown_extensions:
  - pymdownx.highlight:
      pygments_lang_class: true

auto_title

false此选项将自动为所有代码块添加标题，显示所用语言的名称，例如为py块打印Python ：

¥false This option will automatically add a title to all code blocks that shows the name of the language being used, e.g. Python is printed for a py block:

markdown_extensions:
  - pymdownx.highlight:
      auto_title: true

linenums

false此选项将为所有代码块添加行号。如果您希望为部分代码块（而非全部代码块）添加行号，请参阅代码块参考中关于添加行号的部分，其中还包含一些使用行号的技巧：

¥false This option will add line numbers to all code blocks. If you wish to add line numbers to some, but not all code blocks, consult the section on adding line numbers in the code block reference, which also contains some tips on working with line numbers:

markdown_extensions:
  - pymdownx.highlight:
      linenums: true

linenums_style

表格Highlight扩展提供了三种添加行号的方式，其中两种由 Material for MkDocs 支持。 table将代码块包裹在<table>元素中，而pymdownx-inline则将行号渲染为行本身的一部分：

¥table The Highlight extension provides three ways to add line numbers, two of which are supported by Material for MkDocs. While table wraps a code block in a <table> element, pymdownx-inline renders line numbers as part of the line itself:

markdown_extensions:
  - pymdownx.highlight:
      linenums_style: pymdownx-inline

请注意， inline会在实际代码旁边添加行号，这意味着在使用光标选择文本或将代码块复制到剪贴板时，这些行号也会被包含在内。因此，建议使用table或pymdownx-inline 。

¥Note that inline will put line numbers next to the actual code, which means that they will be included when selecting text with the cursor or copying a code block to the clipboard. Thus, the usage of either table or pymdownx-inline is recommended.

anchor_linenums

8.1.0默认值： false – 如果代码块包含行号，启用此设置将使用锚链接包装它们，以便可以更轻松地进行超链接和共享：

¥8.1.0 Default: false – If a code blocks contains line numbers, enabling this setting will wrap them with anchor links, so they can be hyperlinked and shared more easily:

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true

line_spans

设置此选项后，代码块的每一行都会被包裹在一个span中，这对于行突出显示等功能的正常工作至关重要：

¥ When this option is set, each line of a code block is wrapped in a span, which is essential for features like line highlighting to work correctly:

markdown_extensions:
  - pymdownx.highlight:
      line_spans: __span

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

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

使用方法见参考：

¥See reference for usage:

内联高亮¶

¥InlineHilite¶

5.0.0 pymdownx.inlinehilite

¥5.0.0 pymdownx.inlinehilite

InlineHilite扩展添加了对内联代码块语法高亮的支持。它构建于Highlight扩展之上，并从其配置中获取。您可以通过mkdocs.yml启用它：

¥The InlineHilite extension add support for syntax highlighting of inline code blocks. It's built on top of the Highlight extension, from which it sources its configuration. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.inlinehilite

此扩展的配置选项并非特定于 Material for MkDocs，因为它们仅影响 Markdown 解析阶段。唯一的例外是css_class选项，该选项不可更改。请参阅InlineHilite 文档以获取指导。

¥The configuration options of this extension are not specific to Material for MkDocs, as they only impact the Markdown parsing stage. The only exception is the css_class option, which must not be changed. See the InlineHilite documentation for guidance.

使用方法见参考：

¥See reference for usage:

突出显示内联代码块
¥Highlighting inline code blocks

按键¶

¥Keys¶

1.0.0 pymdownx.keys

¥1.0.0 pymdownx.keys

Keys扩展添加了一个简单的语法，允许渲染键盘按键和组合键，例如Ctrl+Alt+Del 。通过mkdocs.yml启用它：

¥The Keys extension adds a simple syntax to allow for the rendering of keyboard keys and combinations, e.g. Ctrl+Alt+Del. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.keys

此扩展的配置选项并非特定于 Material for MkDocs，因为它们仅影响 Markdown 解析阶段。唯一的例外是class选项，该选项不可更改。有关更多信息，请参阅Keys 文档。

¥The configuration options of this extension are not specific to Material for MkDocs, as they only impact the Markdown parsing stage. The only exception is the class option, which must not be changed. See the Keys documentation for more information.

使用方法见参考：

¥See reference for usage:

添加键盘键
¥Adding keyboard keys

智能符号¶

¥SmartSymbols¶

0.1.0 pymdownx.smartsymbols

¥0.1.0 pymdownx.smartsymbols

SmartSymbols扩展可以将一些字符序列转换为相应的符号，例如版权符号或分数。通过mkdocs.yml启用它：

¥The SmartSymbols extension converts some sequences of characters into their corresponding symbols, e.g. copyright symbols or fractions. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.smartsymbols

此扩展的配置选项并非特定于 Material for MkDocs，因为它们仅影响 Markdown 解析阶段。请参阅SmartSymbols 文档以获取指导。

¥The configuration options of this extension are not specific to Material for MkDocs, as they only impact the Markdown parsing stage. See the SmartSymbols documentation for guidance.

片段¶

¥Snippets¶

0.1.0 pymdownx.snippets

¥0.1.0 pymdownx.snippets

Snippets扩展新增了使用简单语法将任意文件（包括其他文档或源文件）的内容嵌入文档的功能。通过mkdocs.yml启用此功能：

¥The Snippets extension adds the ability to embed content from arbitrary files into a document, including other documents or source files, by using a simple syntax. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.snippets

此扩展的配置选项并非特定于 Material for MkDocs，因为它们仅影响 Markdown 解析阶段。有关更多信息，请参阅代码片段文档。

¥The configuration options of this extension are not specific to Material for MkDocs, as they only impact the Markdown parsing stage. See the Snippets documentation for more information.

使用方法见参考：

¥See reference for usage:

超级围栏¶

¥SuperFences¶

0.1.0 pymdownx.superfences

¥0.1.0 pymdownx.superfences

SuperFences扩展允许代码块和内容块任意嵌套，包括警告、标签、列表和所有其他元素。通过mkdocs.yml启用此功能：

¥The SuperFences extension allows for arbitrary nesting of code and content blocks inside each other, including admonitions, tabs, lists and all other elements. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences

支持以下配置选项：

¥The following configuration options are supported:

custom_fences

此选项允许定义自定义围栏的处理程序，例如，保留要在浏览器中解释的Mermaid.js图表的定义：

¥ This option allows to define a handler for custom fences, e.g. to preserve the definitions of Mermaid.js diagrams to be interpreted in the browser:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

请注意，这主要会阻止语法高亮显示。请参阅图表中的参考，了解 Mermaid.js 如何与 Material for MkDocs 集成。

¥Note that this will primarily prevent syntax highlighting from being applied. See the reference on diagrams to learn how Mermaid.js is integrated with Material for MkDocs.

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

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

使用方法见参考：

¥See reference for usage:

标签式¶

¥Tabbed¶

5.0.0 pymdownx.tabbed

¥5.0.0 pymdownx.tabbed

Tabbed扩展允许使用内容选项卡，这是一种将相关内容和代码块分组到可访问选项卡下的简单方法。通过mkdocs.yml启用它：

¥The Tabbed extension allows the usage of content tabs, a simple way to group related content and code blocks under accessible tabs. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true

支持以下配置选项：

¥The following configuration options are supported:

alternate_style

7.3.1错误此选项启用内容选项卡替代样式，该样式在移动视口上具有更好的行为，并且是唯一受支持的样式：

¥7.3.1 false This option enables the content tabs alternate style, which has better behavior on mobile viewports, and is the only supported style:

markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true

combine_header_slug

false此选项启用内容选项卡的 [ combine_header_slug样式] 标志，该标志将标题的 id 添加到选项卡的 id 之前：

¥false This option enables the content tabs' [combine_header_slug style] flag, which prepends the id of the header to the id of the tab:

markdown_extensions:
  - pymdownx.tabbed:
      combine_header_slug: true

slugify

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

¥None 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:

UnicodeUnicode, case-sensitive

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

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

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

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

使用方法见参考：

¥See reference for usage:

任务列表¶

¥Tasklist¶

1.0.0 pymdownx.任务列表

¥1.0.0 pymdownx.tasklist

Tasklist扩展允许使用GitHub Flavored Markdown风格的任务列表，并遵循相同的语法约定。通过mkdocs.yml启用它：

¥The Tasklist extension allows for the usage of GitHub Flavored Markdown inspired task lists, following the same syntactical conventions. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true

支持以下配置选项：

¥The following configuration options are supported:

custom_checkbox

false此选项切换复选框的渲染样式，用漂亮的图标替换原生复选框样式，因此建议：

¥false This option toggles the rendering style of checkboxes, replacing native checkbox styles with beautiful icons, and is therefore recommended:

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true

clickable_checkbox

false此选项切换复选框是否可点击。由于状态不持久，因此从用户体验的角度来看，不建议使用此选项：

¥false This option toggles whether checkboxes are clickable. As the state is not persisted, the use of this option is rather discouraged from a user experience perspective:

markdown_extensions:
  - pymdownx.tasklist:
      clickable_checkbox: true

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

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

使用方法见参考：

¥See reference for usage:

使用任务列表
¥Using task lists

其他库（例如KaTeX）也受支持，只需稍加努力即可集成。有关 KaTeX 的更多指导，请参阅 Arithmatex 文档，因为这超出了 Material for MkDocs 的范围。↩