PyMdown Extensions#

The PyMdown Extensions package is an excellent collection of extensions suited for advanced technical writing. Terminal for MkDocs lists this package as an explicit dependency so it's automatically installed with a supported version.

Suggested PyMdown Extensions#

Caret, Mark & Tilde#

The Caret, Mark, and Tilde extensions add the ability to highlight text and define subscript 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 Terminal for MkDocs, as they only impact the Markdown parsing stage.

See reference for usage:

Snippets#

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 Terminal for MkDocs, as they only impact the Markdown parsing stage. See the Snippets documentation for more information.

See reference for usage:

SuperFences#

The SuperFences extension allows fenced blocks to be nested inside block quotes, lists, or other block elements. Enable it via mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences

This extension is incompatible with the Python Markdown extension markdown.extensions.fenced_code.

Highlight and InlineHilite#

The Highlight and InlineHilite extensions can be used to highlight code blocks. If used with the PyMdown SuperFences extension line numbers can be added as well. Enable them via mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.highlight
  - pymdownx.inlinehilite

See reference for recommended configuration options:

Details#

The Details extension can be used to create admonitions (sometimes called callouts). By default, Terminal for Mkdocs supports three categories. Enable them via mkdocs.yml:

Info

This is an info block

Warning

This is a warning

Important

This is important

markdown_extensions:
  - pymdownx.blocks.details:
      types:
        - name: info 
          class: terminal-alert
          title: Info
        - name: warning
          class: 'terminal-alert terminal-alert-error'
          title: Warning
        - name: important
          class: 'terminal-alert terminal-alert-primary'
          title: Important
  • To use different categories, update the name attribute.
  • To use a custom style, update the class attribute to the name of your custom CSS class (remember to load the custom CSS via the extra_css MkDocs feature).

See reference for usage:

Credit#

This documentation page is based on squidfunk's Material for MkDocs Pymdown Extension documentation.