Added docs on extended formatting

docs/reference/admonitions.md

@@ -246,7 +246,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`info`{: #info}, `todo`
+`info`{: #info }, `todo`
 
 :   !!! info
 

docs/reference/code-blocks.md

@@ -336,18 +336,18 @@ If [Pygments][22] is used, Material for MkDocs provides the [styles for code
 blocks][21], which are built with a custom and well-balanced palette that works
 equally well for both [color schemes][23]:
 
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color`
-- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color`
+* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color`
 
 Let's say you want to change the color of `#!js "strings"`. While there are
 several [types of string tokens][24], Material for MkDocs assigns a single color

docs/reference/content-tabs.md

@@ -108,9 +108,9 @@ _Example_:
 ```
 === "Unordered list"
 
-    - Sed sagittis eleifend rutrum
+    * Sed sagittis eleifend rutrum
-    - Donec vitae suscipit est
+    * Donec vitae suscipit est
-    - Nulla tempor lobortis orci
+    * Nulla tempor lobortis orci
 
 === "Ordered list"
 
@@ -123,9 +123,9 @@ _Result_:
 
 === "Unordered list"
 
-    - Sed sagittis eleifend rutrum
+    * Sed sagittis eleifend rutrum
-    - Donec vitae suscipit est
+    * Donec vitae suscipit est
-    - Nulla tempor lobortis orci
+    * Nulla tempor lobortis orci
 
 === "Ordered list"
 
@@ -149,16 +149,16 @@ _Example_:
         _Example_:
 
         ``` markdown
-        - Sed sagittis eleifend rutrum
+        * Sed sagittis eleifend rutrum
-        - Donec vitae suscipit est
+        * Donec vitae suscipit est
-        - Nulla tempor lobortis orci
+        * Nulla tempor lobortis orci
         ```
 
         _Result_:
 
-        - Sed sagittis eleifend rutrum
+        * Sed sagittis eleifend rutrum
-        - Donec vitae suscipit est
+        * Donec vitae suscipit est
-        - Nulla tempor lobortis orci
+        * Nulla tempor lobortis orci
 
     === "Ordered List"
 
@@ -186,16 +186,16 @@ _Result_:
         _Example_:
 
         ``` markdown
-        - Sed sagittis eleifend rutrum
+        * Sed sagittis eleifend rutrum
-        - Donec vitae suscipit est
+        * Donec vitae suscipit est
-        - Nulla tempor lobortis orci
+        * Nulla tempor lobortis orci
         ```
 
         _Result_:
 
-        - Sed sagittis eleifend rutrum
+        * Sed sagittis eleifend rutrum
-        - Donec vitae suscipit est
+        * Donec vitae suscipit est
-        - Nulla tempor lobortis orci
+        * Nulla tempor lobortis orci
 
     === "Ordered List"
 

docs/reference/formatting.md

@@ -0,0 +1,189 @@
+---
+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][1] is supported, adding the ability to display suggested changes
+for a document.
+
+  [1]: http://criticmarkup.com/
+
+## Configuration
+
+### Critic
+
+[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
+
+The [Critic][3] extension, which is part of [Python Markdown Extensions][4], 
+allows for the __usage of [Critic Markup][1] to highlight changes__ in a
+document, and can be enabled via `mkdocs.yml`:
+
+``` yaml
+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
+        ```
+
+  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_critic.scss
+  [3]: https://facelessuser.github.io/pymdown-extensions/critic/
+  [4]: https://facelessuser.github.io/pymdown-extensions/
+
+### BetterEm
+
+The [BetterEm][5] extension, which is part of [Python Markdown Extensions][4], 
+improves the handling of Markup to emphasize text (e.g. __bold__  and _italic_), 
+and can be enabled via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.betterem:
+      smart_enable: all
+```
+
+  [5]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
+
+### Caret, Mark & Tilde
+
+The [Caret][6], [Mark][7] and [Tilde][8] extensions, which are part of [Python 
+Markdown Extensions][4], allow for the __highlighting of text__, as well as
+__handling sub- and superscripts__:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.caret
+  - pymdownx.mark
+  - pymdownx.tilde
+```
+
+  [6]: https://facelessuser.github.io/pymdown-extensions/caret/
+  [7]: https://facelessuser.github.io/pymdown-extensions/mark/
+  [8]: https://facelessuser.github.io/pymdown-extensions/tilde/
+
+### SmartSymbols
+
+The [SmartSymbols][9] extension, which is also part of [Python Markdown 
+Extensions][4], __converts special characters into their corresponding
+symbols__, and can be enabled via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.smartsymbols
+```
+
+See the [official documentation][9] for a list of supported symbols.
+
+  [9]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
+
+## Usage
+
+### Highlighting changes
+
+When [Critic][10] is enabled, [Critic Markup][1] can be used, which adds the
+ability to _highlight suggested changes_, as well as add _inline comments_ to a 
+document:
+
+  [10]: #critic
+
+_Example_:
+
+``` markdown
+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][11] extensions are enabled, text can be 
+highlighted with a nicer syntax than using the corresponding `mark`, `del` and 
+`ins` HTML tags:
+
+_Example_:
+
+``` markdown 
+* ^^This was inserted^^
+* ==This was marked==
+* ~~This was deleted~~
+```
+
+_Result_:
+
+* ^^This was inserted^^
+* ==This was marked==
+* ~~This was deleted~~
+
+  [11]: #caret-mark-tilde
+
+### Sub- and superscripts
+
+When the [Caret & Tilde][11] extensions are enabled, text can be sub- and 
+superscripted with a nicer syntax than using the corresponding `sub` and `sup` 
+HTML tags:
+
+_Example_:
+
+``` markdown 
+* A^T^A
+* H~2~0
+```
+
+_Result_:
+
+* A^T^A
+* H~2~0
+
+  [11]: #caret-mark-tilde

docs/reference/icons-emojis.md

@@ -49,7 +49,7 @@ about configuration options.
 ### Attribute List
 
 The [Attribute List][10] extension, which is part of the standard Markdown
-library, allows to __add HTML attributes and classes to Markdown elements__,
+library, allows to __add HTML attributes and CSS classes to Markdown elements__,
 and can be enabled via `mkdocs.yml`
 
 ``` yaml
@@ -141,16 +141,16 @@ Then, add the CSS classes to the icons:
 _Example_:
 
 ``` markdown
-- :fontawesome-brands-medium:{: .medium } – Medium
+* :fontawesome-brands-medium:{: .medium } – Medium
-- :fontawesome-brands-twitter:{: .twitter } – Twitter
+* :fontawesome-brands-twitter:{: .twitter } – Twitter
-- :fontawesome-brands-facebook:{: .facebook } – Facebook
+* :fontawesome-brands-facebook:{: .facebook } – Facebook
 ```
 
 _Result_:
 
-- :fontawesome-brands-medium:{: .medium } – Medium
+* :fontawesome-brands-medium:{: .medium } – Medium
-- :fontawesome-brands-twitter:{: .twitter } – Twitter
+* :fontawesome-brands-twitter:{: .twitter } – Twitter
-- :fontawesome-brands-facebook:{: .facebook } – Facebook
+* :fontawesome-brands-facebook:{: .facebook } – Facebook
 
   [17]: #attribute-list
   [18]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style

docs/setup/adding-a-git-repository.md

@@ -59,16 +59,16 @@ theme:
 
 Some popular choices:
 
-- :fontawesome-brands-git: – `fontawesome/brands/git`
+* :fontawesome-brands-git: – `fontawesome/brands/git`
-- :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
+* :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
-- :fontawesome-brands-git-square: – `fontawesome/brands/git-square`
+* :fontawesome-brands-git-square: – `fontawesome/brands/git-square`
-- :fontawesome-brands-github: – `fontawesome/brands/github`
+* :fontawesome-brands-github: – `fontawesome/brands/github`
-- :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt`
+* :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt`
-- :fontawesome-brands-github-square: – `fontawesome/brands/github-square`
+* :fontawesome-brands-github-square: – `fontawesome/brands/github-square`
-- :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
+* :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
-- :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken`
+* :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken`
-- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
+* :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
-- :fontawesome-solid-trash: – `fontawesome/solid/trash`
+* :fontawesome-solid-trash: – `fontawesome/solid/trash`
 
   [4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
 

docs/setup/adding-social-links.md

@@ -37,16 +37,16 @@ For each entry, the following fields are available:
       This field must point to a valid icon path referencing [any icon bundled 
       with the theme][2], or the build will not succeed. Some popular choices:
 
-      - :fontawesome-brands-behance: – `fontawesome/brands/behance`
+      * :fontawesome-brands-behance: – `fontawesome/brands/behance`
-      - :fontawesome-brands-docker: – `fontawesome/brands/docker`
+      * :fontawesome-brands-docker: – `fontawesome/brands/docker`
-      - :fontawesome-brands-github: – `fontawesome/brands/github`
+      * :fontawesome-brands-github: – `fontawesome/brands/github`
-      - :fontawesome-brands-instagram: – `fontawesome/brands/instagram`
+      * :fontawesome-brands-instagram: – `fontawesome/brands/instagram`
-      - :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
+      * :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
-      - :fontawesome-brands-medium: – `fontawesome/brands/medium`
+      * :fontawesome-brands-medium: – `fontawesome/brands/medium`
-      - :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
+      * :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
-      - :fontawesome-brands-product-hunt: – `fontawesome/brands/product-hunt`
+      * :fontawesome-brands-product-hunt: – `fontawesome/brands/product-hunt`
-      - :fontawesome-brands-slack: – `fontawesome/brands/slack`
+      * :fontawesome-brands-slack: – `fontawesome/brands/slack`
-      - :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
+      * :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
 
   [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
   [2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons

docs/setup/setting-up-navigation.md

@@ -196,9 +196,9 @@ to navigate your project documentation via keyboard. There're two modes:
 :   This mode is active when the _search is focused_. It provides several key
     bindings to make search accessible and navigable via keyboard:
 
-    - ++arrow-down++ , ++arrow-up++ : select next / previous result
+    * ++arrow-down++ , ++arrow-up++ : select next / previous result
-    - ++esc++ , ++tab++ : close search dialog
+    * ++esc++ , ++tab++ : close search dialog
-    - ++enter++ : follow selected result
+    * ++enter++ : follow selected result
 
 `global`{: #global }
 
@@ -206,9 +206,9 @@ to navigate your project documentation via keyboard. There're two modes:
     focussed element that is susceptible to keyboard input. The following keys
     are bound:
 
-    - ++f++ , ++s++ , ++slash++ : open search dialog
+    * ++f++ , ++s++ , ++slash++ : open search dialog
-    - ++p++ , ++comma++ : go to previous page
+    * ++p++ , ++comma++ : go to previous page
-    - ++n++ , ++period++ : go to next page
+    * ++n++ , ++period++ : go to next page
 
 Let's say you want to bind some action to the ++x++ key. By using [additional
 JavaScript][11], you can subscribe to the `keyboard$` observable and attach

docs/setup/setting-up-site-search.md

@@ -256,15 +256,15 @@ message format using _discriminated unions_, i.e. through the `type` property
 of the message. See the following interface definitions to learn about the
 message formats:
 
-- [:octicons-file-code-24: `SearchMessage`][17]
+* [:octicons-file-code-24: `SearchMessage`][17]
-- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][18]
+* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][18]
 
 The sequence and direction of messages is rather intuitive:
 
-- :octicons-arrow-right-24: `SearchSetupMessage` 
+* :octicons-arrow-right-24: `SearchSetupMessage`
-- :octicons-arrow-left-24: `SearchReadyMessage`
+* :octicons-arrow-left-24: `SearchReadyMessage`
-- :octicons-arrow-right-24: `SearchQueryMessage` 
+* :octicons-arrow-right-24: `SearchQueryMessage`
-- :octicons-arrow-left-24: `SearchResultMessage`
+* :octicons-arrow-left-24: `SearchResultMessage`
 
   [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
   [16]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers

mkdocs.yml

@@ -168,6 +168,7 @@ nav:
     - Code blocks: reference/code-blocks.md
     - Content tabs: reference/content-tabs.md
     - Footnotes: reference/footnotes.md
+    - Formatting: reference/formatting.md
     - Icons + Emojis: reference/icons-emojis.md
     - Lists: reference/lists.md
     - MathJax: reference/mathjax.md