Skip to content

Python Markdown 扩展

Python Markdown Extensions 包是一个优秀的附加扩展集合，非常适合高级技术写作。MkDocs 的 Material 列出了这个包作为明确的依赖项，因此它会与支持的版本一起自动安装。

支持的扩展

一般来说，所有属于 Python Markdown Extensions 的扩展都应该可以与 MkDocs 的 Material 一起使用。以下列表包括所有原生支持的扩展，意味着它们可以在没有任何进一步调整的情况下工作。

Arithmatex

1.0.0 pymdownx.arithmatex

Arithmatex 扩展允许渲染块和行内方程，并与 MathJax1 无缝集成——一个用于数学排版的库。通过 mkdocs.yml 启用它：

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

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

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()
})
  1. 这将 MathJax 与 instant loading 集成。
extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

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

有关用法的参考：

BetterEm

0.1.0 pymdownx.betterem

BetterEm 扩展改善了在 Markdown 中使用特殊字符强调文本的标记检测，即用于 **bold** 和 _italic_ 格式。通过 mkdocs.yml 启用它：

markdown_extensions:
  - pymdownx.betterem

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

Caption

1.0.0 pymdownx.blocks.caption

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

markdown_extensions:
  - pymdownx.blocks.caption

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

Caret, Mark & Tilde

1.0.0 pymdownx.caret

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

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

此扩展的配置选项并不特定于 MkDocs Material，因为它们仅影响 Markdown 解析阶段。有关指导，请参见 Caret、Mark 和 Tilde documentation。

有关用法的参考：

Critic

1.0.0 pymdownx.critic

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

markdown_extensions:
  - pymdownx.critic

支持以下配置选项：

mode

view 此选项定义了标记的解析方式，即是仅 view 所有建议的更改，还是 accept 或 reject 它们：

markdown_extensions:
  - pymdownx.critic:
      mode: view

markdown_extensions:
  - pymdownx.critic:
      mode: accept

markdown_extensions:
  - pymdownx.critic:
      mode: reject

有关用法的参考：

Details

1.9.0 pymdownx.details

Details 扩展增强了 Admonition 扩展，使得生成的 call-outs 可折叠，允许用户打开和关闭。通过 mkdocs.yml 启用它：

markdown_extensions:
  - pymdownx.details

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

Emoji

1.0.0 pymdownx.emoji

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

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji # (1)!
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  1. Python Markdown Extensions 使用 pymdownx 命名空间，但为了支持图标的内联，必须使用 materialx 命名空间，因为它扩展了 pymdownx 的功能。

支持以下配置选项：

emoji_index

emojione 此选项定义了用于渲染的表情符号集。请注意，由于 restrictions in licensing，不推荐使用 emojione：

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

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

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

此选项允许列出用于 Markdown 或 mkdocs.yml 的其他图标集文件夹，详细说明请参见 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

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

有关用法的参考：

Highlight

5.0.0 pymdownx.highlight

Highlight 扩展添加了对代码块的语法高亮支持（借助 SuperFences）和行内代码块的支持（借助 InlineHilite）。通过 mkdocs.yml 启用它：

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences # (1)!
  1. Highlight 是由 SuperFences 扩展使用来对代码块进行语法高亮，而不是反过来，因此此扩展也需要启用。

支持以下配置选项：

use_pygments

true 此选项允许控制是否在构建时使用 Pygments 进行高亮，或在浏览器中使用 JavaScript 语法高亮：

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

markdown_extensions:
  - pymdownx.highlight:
      use_pygments: false

作为示例，可以通过一些 additional JavaScript 和 mkdocs.yml 中的 additional style sheet 集成 Highlight.js，这是一个 JavaScript 语法高亮工具：

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 扩展没有关联。

所有以下配置选项仅与使用 Pygments 的构建时语法高亮兼容，因此如果将 use_pygments 设置为 false，则不适用。

pygments_lang_class

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

markdown_extensions:
  - pymdownx.highlight:
      pygments_lang_class: true
auto_title

false 此选项将自动为所有代码块添加一个 title，显示所使用语言的名称，例如 Python 会在 py 块中打印：

markdown_extensions:
  - pymdownx.highlight:
      auto_title: true
linenums

false 此选项将为 所有 代码块添加行号。如果您希望为 某些 代码块添加行号，但不是所有代码块，请参阅代码块参考中的 adding line numbers 部分，其中还包含有关处理行号的一些提示：

markdown_extensions:
  - pymdownx.highlight:
      linenums: true
linenums_style

table Highlight 扩展提供三种添加行号的方式，其中两种受到 MkDocs Material 的支持。虽然 table 将代码块包装在 <table> 元素中，但 pymdownx-inline 将行号呈现为行本身的一部分：

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

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

anchor_linenums

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

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
line_spans

当此选项被设置时，代码块的每一行都被包装在一个 span 中，这对像行高亮这样的功能正常工作至关重要：

markdown_extensions:
  - pymdownx.highlight:
      line_spans: __span

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

有关用法的参考：

InlineHilite

5.0.0 pymdownx.inlinehilite

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

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.inlinehilite

此扩展的配置选项并不特定于 MkDocs Material，因为它们仅影响 Markdown 解析阶段。唯一的例外是 css_class 选项，不能更改。有关指导，请参见 InlineHilite documentation。

有关用法的参考：

Keys

1.0.0 pymdownx.keys

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

markdown_extensions:
  - pymdownx.keys

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

有关用法的参考：

SmartSymbols

0.1.0 pymdownx.smartsymbols

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

markdown_extensions:
  - pymdownx.smartsymbols

此扩展的配置选项并不特定于 MkDocs Material，因为它们仅影响 Markdown 解析阶段。有关指导，请参见 SmartSymbols documentation。

Snippets

0.1.0 pymdownx.snippets

Snippets 扩展添加了将任意文件的内容嵌入文档的能力，包括其他文档或源文件，使用简单的语法。通过 mkdocs.yml 启用它：

markdown_extensions:
  - pymdownx.snippets

此扩展的配置选项并不特定于 MkDocs Material，因为它们仅影响 Markdown 解析阶段。有关更多信息，请参见 Snippets documentation。

有关用法的参考：

SuperFences

0.1.0 pymdownx.superfences

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

markdown_extensions:
  - pymdownx.superfences

支持以下配置选项：

custom_fences

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

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

请注意，这将主要防止应用语法高亮。有关如何将 Mermaid.js 集成到 MkDocs Material 中的参考，请参见 diagrams。

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

有关用法的参考：

Tabbed

5.0.0 pymdownx.tabbed

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

markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true

支持以下配置选项：

alternate_style

7.3.1 false 此选项启用内容标签的 alternate style，该样式在 better behavior on mobile viewports 上表现更好，并且是唯一支持的样式：

markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true
combine_header_slug

false 此选项启用内容标签的 [combine_header_slug style] 标志，该标志将标题的 ID 前缀添加到标签的 ID：

markdown_extensions:
  - pymdownx.tabbed:
      combine_header_slug: true
slugify

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

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

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

有关用法的参考：

Tasklist

1.0.0 pymdownx.tasklist

Tasklist 扩展允许使用受 GitHub Flavored Markdown 启发的 task lists，遵循相同的语法约定。通过 mkdocs.yml 启用它：

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true

支持以下配置选项：

custom_checkbox

false 此选项切换复选框的渲染样式，用美观的图标替换原生复选框样式，因此推荐使用：

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true
clickable_checkbox

false 此选项切换复选框是否可点击。由于状态不会被保留，因此从用户体验的角度来看，使用此选项是 相当不鼓励 的：

markdown_extensions:
  - pymdownx.tasklist:
      clickable_checkbox: true

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

有关用法的参考：

  1. 其他库如 KaTeX 也受支持，并可以通过一些额外的努力进行集成。有关进一步指导，请参见 Arithmatex documentation on KaTeX，因为这超出了 MkDocs Material 的范围。 ↩