mkdocs-material/docs/setup/extensions/python-markdown-extensions.md

template
overrides/main.html

Python Markdown Extensions

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

Supported extensions

The following extensions are all supported by Material for MkDocs and therefore strongly recommended. See the overview page for a minimal and recommended configuration.

Arithmatex

:octicons-workflow-24: Extension · :octicons-tag-24: 1.0.0 ... present

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

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:

=== ":octicons-file-code-16: docs/javascripts/config.js"

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

document$.subscribe(() => {
  MathJax.typesetPromise()
})
```

=== ":octicons-file-code-16: mkdocs.yml"

``` yaml
extra_javascript:
  - javascripts/config.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
```

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

See reference for usage:

• Using block syntax

• Using inline block syntax

BetterEm

:octicons-workflow-24: Extension · :octicons-tag-24: 0.1.0 ... present

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

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.

Caret, Mark & Tilde

:octicons-workflow-24: Extension · :octicons-tag-24: 1.0.0 ... present

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

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:

• Highlighting text

• Sub- and superscripts

Critic

:octicons-workflow-24: Extension · :octicons-tag-24: 1.0.0 ... present

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

:octicons-milestone-24: Default: 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 changes"

``` yaml
markdown_extensions:
  - pymdownx.critic:
      mode: view
```

=== "Accept changes"

``` yaml
markdown_extensions:
  - pymdownx.critic:
      mode: accept
```

=== "Reject changes"

``` yaml
markdown_extensions:
  - pymdownx.critic:
      mode: reject
```

See reference for usage:

• Highlighting changes

Details

:octicons-workflow-24: Extension · :octicons-tag-24: 1.9.0 ... present

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

:octicons-workflow-24: Extension · :octicons-tag-24: 1.0.0 ... present

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:materialx.emoji.twemoji # (1)
      emoji_generator: !!python/name:materialx.emoji.to_svg

1. 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{ #emoji_index }

:octicons-milestone-24: Default: 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:materialx.emoji.twemoji

emoji_generator{ #emoji_generator }

:octicons-milestone-24: Default: 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:materialx.emoji.to_svg

options.custom_icons{ #custom_icons }

:octicons-milestone-24: Default: none – This option allows to list folders with additional icon sets to be used in Markdown documents, which is explained in more detail in the icon customization guide.

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

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

See reference for usage:

• Using emojis

• Using icons

• Using icons in templates

Highlight

:octicons-workflow-24: Extension · :octicons-tag-24: 5.0.0 ... present · :octicons-zap-24: Supersedes CodeHilite

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
  - pymdownx.superfences # (1)

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

   However, this only applies for when Pygments is used. If you use a JavaScript syntax highlighter, SuperFences might not be necessary, but it's strongly recommended anyway.

The following configuration options are supported:

use_pygments{ #use-pygments }

:octicons-milestone-24: Default: true – This option allows to control whether highlighting should be carried out during build time using Pygments or runtime with a JavaScript syntax highlighter:

=== "Pygments"

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

=== "JavaScript"

``` yaml
markdown_extensions:
  - pymdownx.highlight:
      use_pygments: false
```

As an example, [Highlight.js], a JavaScript syntax highlighter, can be 
integrated with some [additional JavaScript] and [CSS][additional CSS]
in `mkdocs.yml`:

=== ":octicons-file-code-16: docs/javascripts/config.js"

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

=== ":octicons-file-code-16: mkdocs.yml"

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

Note that [Highlight.js] has no affiliation with the Highlight extension.

linenums{ #linenums }

:octicons-milestone-24: Default: 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{ #linenums-style }

:octicons-milestone-24: Default: table – The Highlight extension provides three ways to add line numbers, all of which are supported by Material for MkDocs. While table wraps a code block in a table, inline and pymdownx-inline render line numbers as part of the line itself:

markdown_extensions:
  - pymdownx.highlight:
      linenums_style: 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.

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

See reference for usage:

• Specifying the language

• Adding line numbers

• Highlighting specific lines

• Custom syntax theme

InlineHilite

:octicons-workflow-24: Extension · :octicons-tag-24: 5.0.0 ... present

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

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

:octicons-workflow-24: Extension · :octicons-tag-24: 1.0.0 ... present

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

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.

SmartSymbols

:octicons-workflow-24: Extension · :octicons-tag-24: 0.1.0 ... present

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

markdown_extensions:
  - pymdownx.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

:octicons-workflow-24: Extension · :octicons-tag-24: 0.1.0 ... present

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

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:

• Embedding external files

SuperFences

:octicons-workflow-24: Extension · :octicons-tag-24: 5.0.0 ... present · :octicons-zap-24: Supersedes Fenced Code Blocks

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

:octicons-milestone-24: Default: none – 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

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.

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

See reference for usage:

• Using flowcharts

• Using sequence diagrams

• Using state diagrams

• Using class diagrams

• Using entity-relationship diagrams

Tabbed

:octicons-workflow-24: Extension · :octicons-tag-24: 5.0.0 ... present

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

:octicons-milestone-24: Default: false · [:octicons-tag-24: 7.3.1] Tabbed alternate support – This option enables the alternate style of content tabs, which has better behavior on smaller screen sizes, and thus is strongly recommended:

markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true 

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

See reference for usage:

• Grouping code blocks

• Grouping other content

• Embedded content

Tasklist

:octicons-workflow-24: Extension · :octicons-tag-24: 1.0.0 ... present

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{ #custom-checkbox }

:octicons-milestone-24: Default: false · This option toggles the rendering style of checkboxes, replacing native checkbox styles with beautiful icons, and is therefore strongly recommended:

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true

clickable_checkbox{ #clickable-checkbox }

:octicons-milestone-24: Default: 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

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

See reference for usage:

• Using task lists

---

1. Other libraries like KaTeX are also supported and can be integrated with some additional effort. See the Arithmatex documentation on KaTeX for further guidance, as this is beyond the scope of Material for MkDocs. ↩︎