Formatting
Material Support
MaterialX 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⚓︎
Configuration Support
This configuration enables support for keyboard keys, tracking changes in documents, defining sub- and superscript and highlighting text. Add the following lines to mkdocs.yml:
See additional configuration options:
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:
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.
==}Rendered (Highlighting) Markdown⚓︎
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.
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.
This Is The Rendered HTML
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 */.
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 Changes (Incorrect Method)⚓︎
Highlighting Changes (Incorrect Method)
The same block of code below, but without the <div class="highlight"><span class="filename"> wrapper and without the {<span></span>-- protection that blinds pymdownx.critic, demonstrates the failure mode directly. Left as a plain fenced code block, Critic's preprocessor reads and renders the syntax before the fence has any chance to shield it — the "raw" content shown below is already fully processed.
This defeats the entire purpose of the code box. A copy button is pointless if the text it copies isn't the raw syntax the reader actually needs — they'd have to manually retype the correct source from scratch, which is precisely the problem this case study set out to solve.
Note: the specific corruption observed wasn't a single character dropping from the closing tag as first suspected during troubleshooting — Critic actually consumed forward past the missing closer, collapsing "deleted" and the entire next clause together before the run finally terminated.
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:
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.
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⚓︎
Highlighting Text
When Caret, Mark & Tilde are enabled, text can be highlighted with a simple syntax, which is more convenient that directly using the corresponding:
mark, ins and del HTML tags:
Sub- and Superscripts⚓︎
Sub- and Superscripts
When Caret & Tilde are enabled, text can be sub- and superscripted with a simple syntax, which is more convenient than directly using the corresponding sub and sup HTML tags:
- H2O
- ATA
Adding Keyboard Keys⚓︎
Adding Keyboard Keys
When Keys is enabled, keyboard keys can be rendered with a simple syntax. Consult the Python Markdown Extensions documentation to learn about all available shortcodes:
Ctrl ＋ Alt ＋ Del