Python Markdown Extensions¶
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¶
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¶
The Arithmatex extension allows for rendering of block and inline block equations and integrates seamlessly with MathJax1 – a library for mathematical typesetting. Enable it via mkdocs.yml
:
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:
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¶
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
:
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¶
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
:
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¶
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
:
The following configuration options are supported:
mode
-
Default:
view
– This option defines how the markup should be parsed, i.e. whether to justview
all suggested changes, or alternativelyaccept
orreject
them:
See reference for usage:
Details¶
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
:
No configuration options are available. See reference for usage:
Emoji¶
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
- Python Markdown Extensions uses the
pymdownx
namespace, but in order to support the inlining of icons, thematerialx
namespace must be used, as it extends the functionality ofpymdownx
.
The following configuration options are supported:
emoji_index
-
Default:
emojione
– This option defines which set of emojis is used for rendering. Note that the use ofemojione
is not recommended due to restrictions in licensing: emoji_generator
-
Default:
to_png
– This option defines how the resolved emoji or icon shortcode is render. Note that icons can only be used together with theto_svg
configuration: options.custom_icons
-
Default: none – 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:
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 · Extension · 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
:
- 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
-
Default:
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:As an example, Highlight.js, a JavaScript syntax highlighter, can be integrated with some additional JavaScript and an additional style sheet in
mkdocs.yml
:Note that Highlight.js has no affiliation with the Highlight extension.
All following configuration options are only compatible with build-time syntax highlighting using Pygments, so they don't apply if
use_pygments
is set tofalse
. auto_title
-
Default:
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 apy
block: linenums
-
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: linenums_style
-
Default:
table
– The Highlight extension provides three ways to add line numbers, two of which are supported by Material for MkDocs. Whiletable
wraps a code block in a<table>
element,pymdownx-inline
renders line numbers as part of the line itself: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 eithertable
orpymdownx-inline
is recommended. anchor_linenums
-
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:
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 code blocks
- Adding a title
- Adding line numbers
- Highlighting specific lines
- Custom syntax theme
InlineHilite¶
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
:
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:
Keys¶
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
:
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:
SmartSymbols¶
The SmartSymbols extension converts some sequences of characters into their corresponding symbols, e.h. copyright symbols or fractions. Enable it via mkdocs.yml
:
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¶
Snippets扩展通过使用简单的语法将任意文件的内容嵌入到文档中,包括其他文档或源文件。 通过mkdocs.yml
启用它:
这个扩展的配置选项不是特定于 Material for MkDocs,因为它们只影响 Markdown 解析阶段。 更多信息请参见Snippets 文档。
用法参考:
SuperFences¶
0.1.0 · Extension · 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
:
The following configuration options are supported:
custom_fences
-
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, which is why they may yield unexpected results. Use them at your own risk.
See reference for usage:
- Using annotations
- Using code blocks
- Using content tabs
- Using flowcharts
- Using sequence diagrams
- Using state diagrams
- Using class diagrams
- Using entity-relationship diagrams
Tabbed¶
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
:
The following configuration options are supported:
Default: false
· Required – This option enables the content tabs alternate style, which has better behavior on mobile viewports, and is the only supported style:
``` yaml
markdown_extensions:
- pymdownx.tabbed:
alternate_style: true
```
slugify
-
Default:
headerid.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:
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¶
The Tasklist extension allows for the usage of GitHub Flavored Markdown inspired task lists, following the same syntactical conventions. Enable it via mkdocs.yml
:
The following configuration options are supported:
custom_checkbox
-
Default:
false
· This option toggles the rendering style of checkboxes, replacing native checkbox styles with beautiful icons, and is therefore recommended: clickable_checkbox
-
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:
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:
-
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. ↩