Formatting¶

Material for MkDocs provides support for several HTML elements that can be used to highlight sections of a document or apply specific formatting. Additionally, Critic Markup is supported, adding the ability to display suggested changes for a document.

Configuration¶

Critic¶

Source · Extension

The Critic extension, which is part of Python Markdown Extensions, allows for the usage of Critic Markup to highlight changes in a document, and can be enabled via mkdocs.yml:

markdown_extensions:
  - pymdownx.critic

The following options are supported:

mode

Default: view – This option defines how the markup should be parsed, i.e. whether to just view all suggest changes, or alternatively accept or reject them:

View changes

markdown_extensions:
  - pymdownx.critic:
      mode: view

Accept changes

markdown_extensions:
  - pymdownx.critic:
      mode: accept

Reject changes

markdown_extensions:
  - pymdownx.critic:
      mode: reject

BetterEm¶

The BetterEm extension, which is part of Python Markdown Extensions, improves the handling of Markup to emphasize text (e.g. bold and italic), and can be enabled via mkdocs.yml:

markdown_extensions:
  - pymdownx.betterem:
      smart_enable: all

Caret, Mark & Tilde¶

The Caret, Mark and Tilde extensions, which are part of Python Markdown Extensions, allow for the highlighting of text, as well as handling sub- and superscripts:

markdown_extensions:
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde

SmartSymbols¶

The SmartSymbols extension, which is also part of Python Markdown Extensions, converts special characters into their corresponding symbols, and can be enabled via mkdocs.yml:

markdown_extensions:
  - pymdownx.smartsymbols

See the official documentation for a list of supported symbols.

Usage¶

Highlighting changes¶

When Critic is enabled, Critic Markup can be used, which adds the ability to highlight suggested changes, as well as add inline comments to a document:

Example:

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

{​==

Formatting can also be applied to blocks, by putting the opening and closing
tags on separate lines and adding new lines between the tags and the content.

==}

Result:

Text can be deleted and replacement text added. This can also be combined into onea single operation. Highlighting is also possible and comments can be added inline.

Highlighting text¶

When the Caret, Mark & Tilde extensions are enabled, text can be highlighted with a nicer syntax than using the corresponding mark, ins and del HTML tags:

Example:

- ==This was marked==
- ^^This was inserted^^
- ~~This was deleted~~

Result:

• This was marked
• This was inserted
• This was deleted

Sub- and superscripts¶

When the Caret & Tilde extensions are enabled, text can be sub- and superscripted with a nicer syntax than using the corresponding sub and sup HTML tags:

Example:

- H~2~0
- A^T^A

Result:

• H₂0
• A^TA