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
```

Arithmatex can be configured in many different ways, for which Material for MkDocs might not provide native support. See the Arithmatex documentation for more information.

See reference for usage:

• Using block syntax

• Using inline block syntax

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 Markdown document, e.g. for tracking changes. 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

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.

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

No configuration options are supported. See reference for usage:

• Highlighting inline code blocks

Snippets

[:octicons-workflow-24: Extension][Snippets] · [:octicons-tag-24: 0.1.0 – present][Snippets support]

SuperFences

TODO: document Mermaid setup!

Tabbed

Tasklist

Other

• Caret
• Keys
• MagicLink
• Mark
• SmartSymbols
• Tilde

---

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. ↩︎