mkdocs-material/docs/reference/formatting.md

template
overrides/main.html

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

:octicons-file-code-24: Source · :octicons-workflow-24: 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{: #mode }

:octicons-milestone-24: 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"

``` yaml
markdown_extensions:
  - pymdownx.critic:
      mode: view
```

=== "Accept changes"

``` yaml
markdown_extensions:
  - pymdownx.critic:
      mode: accept
```

=== "Reject changes"

``` yaml
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 {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.

==}

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~2~0

• A^T^A