Skip to content

Extensions

Markdown is a very small language with a kind-of reference implementation called John Gruber's Markdown. Python Markdown and Python Markdown Extensions are two packages that enhance the Markdown writing experience, adding useful syntax extensions for technical writing.

Supported extensions⚓︎

The following extensions are all supported by MaterialX for MkDocs and therefore strongly recommended. Click on each extension to learn about its purpose and configuration:

Configuration⚓︎

Extensions are configured as part of mkdocs.yml – the MkDocs configuration file. The following sections contain two example configurations to bootstrap your documentation project.

Minimal configuration⚓︎

This configuration is a good starting point for when you're using MaterialX for MkDocs for the first time. The bestidea is to explore the reference, and gradually add what you want to use:

markdown_extensions:

  # Python Markdown
  - toc:
      permalink: true

  # Python Markdown Extensions
  - pymdownx.highlight
  - pymdownx.superfences

This configuration enables all Markdown-related features of MaterialX for MkDocs and is great for experienced users bootstrapping a new documentation project:

markdown_extensions:

  # Python Markdown
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true

  # Python Markdown Extensions
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde