mkdocs-material/docs/extensions/pymdown.md

PyMdown Extensions

PyMdown Extensions is a collection of Markdown extensions that add some great features to the standard Markdown library. For this reason, the installation of this package is highly recommended as it's well-integrated with the Material theme.

Installation

The PyMdown Extensions package can be installed with the following command:

pip install pymdown-extensions

The following list of extensions that are part of the PyMdown Extensions package are recommended to be used together with the Material theme:

markdown_extensions:
  - pymdownx.betterem(smart_enable=all)
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.githubemoji
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist(custom_checkbox=true)
  - pymdownx.tilde

Additionally, there is a MathJax integration which should only be switched on if needed, as it adds a few hundred kb of JavaScript:

markdown_extensions:
  - pymdownx.arithmatex

Usage

GitHub Flavored Markdown

Most of the extensions included in the PyMdown Extensions package try to bring the Markdown experience closer to GitHub Flavored Markdown (GFM).

The PyMdown Extensions package adds a shorthand to enable all of the included extensions that provide the GFM experience. However, usage of the shorthand is discouraged, because some extensions are not supported, as the Material theme uses the counterparts included in the standard Markdown library.

BetterEm

BetterEm improves the handling of emphasis markup (bold and italic) within Markdown by providing a more sophisticated parser for better detecting start and end tokens. Read the documentation for usage notes.

GitHub Emoji

GitHub Emoji adds the ability to insert emojis, which does not only include the :octocat: emojis, but also a 💩-load of emojis that we use in our daily lives. See the Emoji Cheat Sheet for a list of all available emojis. Happy scrolling 🎉

MagicLink

MagicLink detects links in Markdown and auto-generates the necessary markup, so no special syntax is required. It auto-links HTTP(S) and FTP links, as well as references to email addresses:

SuperFences

SuperFences provides the ability to nest code blocks under blockquotes, lists and other block elements, which the Fenced Code Blocks extension from the standard Markdown library doesn't parse correctly.

Tasklist

Tasklist adds support for styled checkbox lists. This is useful for keeping track of tasks and showing what has been done and has yet to be done. Checkbox lists are like regular lists, but prefixed with [ ] for empty or [x] for filled checkboxes.

Example:

* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
* [x] Nulla lobortis egestas semper
* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
* [ ] Vestibulum convallis sit amet nisi a tincidunt
    * [x] In hac habitasse platea dictumst
    * [x] In scelerisque nibh non dolor mollis congue sed et metus
    * [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
    * [ ] Praesent sed risus massa
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi

Result:

• Lorem ipsum dolor sit amet, consectetur adipiscing elit
• Nulla lobortis egestas semper
• Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
• Vestibulum convallis sit amet nisi a tincidunt
  • In hac habitasse platea dictumst
  • In scelerisque nibh non dolor mollis congue sed et metus
  • Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
  • Praesent sed risus massa
• Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
• Nulla vel eros venenatis, imperdiet enim id, faucibus nisi

Tilde

Tilde provides an easy way to strike through cross out text. The portion of text that should be erased must be enclosed in two tildes ~~...~~, and the extension will take care of the rest.

More syntactic sugar

Caret

Caret is the sister extension of Tilde and makes it possible to highlight ^^inserted text^^. The portion of text that should be marked as added must be enclosed in two carets ^^...^^.

Mark

Mark adds the ability to ==highlight text== like it was marked with a ==yellow text marker==. The portion of text that should be highlighted must be enclosed in two equal signs ==...==.

SmartSymbols

SmartSymbols converts markup for special characters into their corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...).

Critic

Critic implements Critic Markup, a Markdown extension that enables the tracking of changes (additions, deletions and comments) on documents. During compilation of the Markdown document, changes can be rendered (default), accepted or rejected.

Text can be {--deleted--} and replacement text {++added++}. This can also be combined in {one~>a single} operation. {==Highlighting==} is also possible {>>and comments can be added inline<<}.

Math and code highlighting

Arithmatex

Arithmatex integrates Material with MathJax which parses block-style and inline equations written in TeX markup and outputs them in mathematical notation. See this thread for a short introduction and quick reference on how to write equations in TeX syntax.

Blocks

Blocks are enclosed in :::tex $$...$$ which are placed on separate lines.

Example:

$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$

Result:

\frac{n!}{k!(n-k)!} = \binom{n}{k}

Inline

Inline equations need to be enclosed in :::tex $...$:

Example:

Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$

Result:

Lorem ipsum dolor sit amet: p(x|y) = \frac{p(y|x)p(x)}{p(y)}

Inlinehilite

Inlinehilite adds support for inline code highlighting. It's useful for short snippets included within body copy, e.g. #!js var test = 0; and can be achived by prefixing inline code with a shebang and language identifier, e.g. #!js.