Added documentation for Python Markdown Extensions

docs/setup/extensions/index.md

@@ -3,4 +3,61 @@ template: overrides/main.html
 title: Extensions
 ---
 
-Add minimal example.
+# Extensions
+
+=== "Recommended"
+
+    ``` yaml
+    markdown_extensions:
+
+      # Python Markdown
+      - abbr
+      - admonition
+      - attr_list
+      - def_list
+      - footnotes
+      - meta
+      - md_in_html
+      - toc:
+          permalink: true
+
+      # Python Markdown Extensions
+      - pymdownx.arithmatex:
+          generic: true
+      - pymdownx.betterem:
+          smart_enable: all
+      - pymdownx.caret
+      - pymdownx.details
+      - pymdownx.emoji:
+          emoji_index: !!python/name:materialx.emoji.twemoji
+          emoji_generator: !!python/name:materialx.emoji.to_svg
+      - pymdownx.highlight
+      - pymdownx.inlinehilite
+      - pymdownx.keys
+      - pymdownx.mark
+      - pymdownx.smartsymbols
+      - pymdownx.superfences
+      - pymdownx.tabbed:
+          alternate_style: true
+      - pymdownx.tasklist:
+          custom_checkbox: true
+      - pymdownx.tilde
+    ```
+
+=== "Minimal"
+
+    ``` yaml
+    markdown_extensions:
+
+      # Python Markdown
+      - meta
+      - toc:
+          permalink: true
+
+      # Python Markdown Extensions
+      - pymdownx.highlight
+      - pymdownx.inlinehilite
+      - pymdownx.superfences
+      - pymdownx.tabbed:
+          alternate_style: true
+    ```

docs/setup/extensions/python-markdown-extensions.md

@@ -4,14 +4,141 @@ template: overrides/main.html
 
 # Python Markdown Extensions
 
+The [Python Markdown Extensions] package is an excellent collection of Markdown
+extensions that make technical writing a breeze. Material for MkDocs views this 
+package as a sibling of its own, which is why most provided extensions are
+already natively supported.
+
+  [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+
 ## Supported extensions
 
+The following extensions are all supported by Material for MkDocs and therefore
+strongly recommended. See the [overview][Extensions] page for a minimal and
+recommended configuration.
+
+  [Extensions]: index.md
+
 ### Arithmatex
 
+[:octicons-workflow-24: Extension][Arithmatex] ·
+[:octicons-tag-24: 1.0.0 – present][Arithmatex support]
+
+The [Arithmatex] extension allows for rendering of block and inline equations,
+and integrates seamlessly with [MathJax][^1], a library for mathematical
+typesetting. Enable it via `mkdocs.yml`:
+
+  [^1]:
+    Other libraries like [KaTeX] are also supported and can be integrated with
+    some additional effort. See the [Arithmatex documentation on KaTeX] for
+    further guidance, as this is beyond the scope of Material for MkDocs.
+
+``` yaml
+markdown_extensions:
+  - pymdownx.arithmatex:
+      generic: true
+```
+
+Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and 
+the JavaScript runtime need to be included, which can be done with a few lines
+of [additional JavaScript]:
+
+=== "`docs/javascripts/config.js`"
+
+    ``` js
+    window.MathJax = {
+      tex: {
+        inlineMath: [["\\(", "\\)"]],
+        displayMath: [["\\[", "\\]"]],
+        processEscapes: true,
+        processEnvironments: true
+      },
+      options: {
+        ignoreHtmlClass: ".*|",
+        processHtmlClass: "arithmatex"
+      }
+    };
+
+    document$.subscribe(() => {
+      MathJax.typesetPromise()
+    })
+    ```
+
+=== "`mkdocs.yml`"
+
+    ``` yaml
+    extra_javascript:
+      - javascripts/config.js
+      - https://polyfill.io/v3/polyfill.min.js?features=es6
+      - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+    ```
+
+Arithmatex can be configured in many different ways, for which Material for
+MkDocs  might not provide native support. See the [Arithmatex documentation][Arithmatex] for more information.
+
+  [Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
+  [Arithmatex support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
+  [Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex
+  [MathJax]: https://www.mathjax.org/
+  [KaTeX]: https://github.com/Khan/KaTeX
+  [additional JavaScript]: ../../customization.md#additional-javascript
+
 ### Critic
 
+[:octicons-workflow-24: Extension][Critic] ·
+[:octicons-tag-24: 1.0.0 – present][Critic support]
+
+The [Critic] extension allows for the usage of [Critic Markup] to highlight
+additions, deletions or substitutions in a Markdown documents. It can be enabled
+via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.critic
+```
+
+The following configuration 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
+        ```
+
+  [Critic]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
+  [Critic support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
+  [Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
+
 ### Details
 
+The [Details] extension supercharges the [Admonition] extension, making the
+resulting _call-outs_ collapsible, rendering
+
+
 ### Emoji
 
 ### Highlight

docs/setup/extensions/python-markdown.md

@@ -14,16 +14,16 @@ is a list of all supported extensions, linking to the relevant sections of the
 
 ## Supported extensions
 
-The following [Python Markdown] extensions are supported by Material for
+The following extensions are all supported by Material for MkDocs and therefore
-MkDocs, and are therefore strongly recommended. See the [Extensions] page for
+strongly recommended. See the [overview][Extensions] page for a minimal and
-a minimal configuration.
+recommended configuration.
 
   [Extensions]: index.md
 
 ### Abbreviations
 
 [:octicons-workflow-24: Extension][Abbreviations] ·
-[:octicons-tag-24: 1.0.0 – present][Abbreviations added]
+[:octicons-tag-24: 1.0.0 – present][Abbreviations support]
 
 The [Abbreviations] extension adds the ability to add a small tooltip to an
 element, by wrapping it with an `abbr` tag. Note that only plain text is
@@ -40,14 +40,14 @@ No configuration options are available. See reference for usage:
 - [Adding a glossary]
 
   [Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
-  [Abbreviations added]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
+  [Abbreviations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Adding abbreviations]: ../../reference/abbreviations.md#adding-abbreviations
   [Adding a glossary]: ../../reference/abbreviations.md#adding-a-glossary
 
 ### Admonition
 
 [:octicons-workflow-24: Extension][Admonition] ·
-[:octicons-tag-24: 0.1.0 – present][Admonition added]
+[:octicons-tag-24: 0.1.0 – present][Admonition support]
 
 The [Admonition] extension adds support for admonitions, more commonly known as 
 _call-outs_, which can be added to Markdown by using a simple syntax. Enable it
@@ -60,12 +60,14 @@ markdown_extensions:
 
 No configuration options are available. See reference for usage:
 
+- [Adding admonitions]
 - [Changing the title]
 - [Removing the title]
 - [Supported types]
 
   [Admonition]: https://python-markdown.github.io/extensions/admonition/
-  [Admonition added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [Admonition support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [Adding admonitions]: ../../reference/admonitions.md#usage
   [Changing the title]: ../../reference/admonitions.md#changing-the-title
   [Removing the title]: ../../reference/admonitions.md#removing-the-title
   [Supported types]: ../../reference/admonitions.md#supported-types
@@ -73,7 +75,7 @@ No configuration options are available. See reference for usage:
 ### Attribute Lists
 
 [:octicons-workflow-24: Extension][Attribute Lists] ·
-[:octicons-tag-24: 0.1.0 – present][Attribute Lists added]
+[:octicons-tag-24: 0.1.0 – present][Attribute Lists support]
 
 The [Attribute Lists] extension allows to add HTML attributes and CSS classes
 to [almost every][Attribute Lists limitations] Markdown inline- and block-level
@@ -92,7 +94,7 @@ No configuration options are available. See reference for usage:
 - [Image lazy-loading]
 
   [Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
-  [Attribute Lists added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [Attribute Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
   [Adding buttons]: ../../reference/buttons.md#adding-buttons
   [Adding icons with colors]: ../../reference/buttons.md#with-colors
@@ -102,7 +104,7 @@ No configuration options are available. See reference for usage:
 ### Definition Lists
 
 [:octicons-workflow-24: Extension][Definition Lists] ·
-[:octicons-tag-24: 1.1.0 – present][Definition Lists added]
+[:octicons-tag-24: 1.1.0 – present][Definition Lists support]
 
 The [Definition Lists] extension adds the ability to add definition lists (more
 commonly known as [description lists] `dl` in HTML) to any Markdown document.
@@ -118,14 +120,14 @@ No configuration options are available. See reference for usage:
 - [Using definition lists]
 
   [Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
-  [Definition Lists added]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
+  [Definition Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
   [description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
   [Using definition lists]: ../../reference/lists.md#using-definition-lists
 
 ### Footnotes
 
 [:octicons-workflow-24: Extension][Footnotes] ·
-[:octicons-tag-24: 1.0.0 – present][Footnotes added]
+[:octicons-tag-24: 1.0.0 – present][Footnotes support]
 
 The [Footnotes] extension allows to define footnotes inline with the content,
 which are then rendered after the content of the Markdown document. Enable it
@@ -142,14 +144,14 @@ No configuration options are supported. See reference for usage:
 - [Adding footnote content]
 
   [Footnotes]: https://python-markdown.github.io/extensions/footnotes/
-  [Footnotes added]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
+  [Footnotes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references
   [Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content
 
 ### Metadata
 
 [:octicons-workflow-24: Extension][Metadata] ·
-[:octicons-tag-24: 1.0.0 – present][Metadata added]
+[:octicons-tag-24: 1.0.0 – present][Metadata support]
 
 The [Metadata] extension adds the ability to attach arbitrary key-value pairs
 to a Markdown document via front matter written in YAML syntax. It can be
@@ -168,7 +170,7 @@ No configuration options are available. See reference for usage:
 - [Adding tags]
 
   [Metadata]: https://python-markdown.github.io/extensions/meta_data/
-  [Metadata added]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
+  [Metadata support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Setting the page title]: ../../reference/meta-tags.md#setting-the-page-title
   [Setting the page description]: ../../reference/meta-tags.md#setting-the-page-description
   [Hiding the sidebars]: ../../setup/setting-up-navigation.md#hiding-the-sidebars
@@ -177,7 +179,7 @@ No configuration options are available. See reference for usage:
 ### Markdown in HTML
 
 [:octicons-workflow-24: Extension][Markdown in HTML] ·
-[:octicons-tag-24: 0.1.0 – present][Markdown in HTML added]
+[:octicons-tag-24: 0.1.0 – present][Markdown in HTML support]
 
 The [Markdown in HTML] extension allows the author to write Markdown inside of
 HTML, which is useful for wrapping Markdown with custom markup. Enable it via
@@ -199,13 +201,13 @@ No configuration options are available. See reference for usage:
 - [Image captions]
 
   [Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
-  [Markdown in HTML added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [Markdown in HTML support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Image captions]: ../../reference/images.md#image-captions
 
 ### Table of Contents
 
 [:octicons-workflow-24: Extension][Table of Contents] ·
-[:octicons-tag-24: 0.1.0 – present][Table of Contents added]
+[:octicons-tag-24: 0.1.0 – present][Table of Contents support]
 
 The [Table of Contents] extension generates a table of contents from a Markdown
 document, which Material for MkDocs will render as part of the resulting page.
@@ -289,13 +291,13 @@ The following configuration options are supported:
         ```
 
   [Table of Contents]: https://python-markdown.github.io/extensions/toc/
-  [Table of Contents added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [Table of Contents support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Pymdownx Slug]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
 
 ### Tables
 
 [:octicons-workflow-24: Extension][Tables] ·
-[:octicons-tag-24: 0.1.0 – present][Tables added]
+[:octicons-tag-24: 0.1.0 – present][Tables support]
 
 The [Tables] extension adds the ability to create tables in Markdown documents
 by using a simple syntax. Enabled it via `mkdocs.yml` (albeit it should be
@@ -312,7 +314,7 @@ No configuration options are available. See reference for usage:
 - [Column alignment]
 
   [Tables]: https://python-markdown.github.io/extensions/tables/
-  [Tables added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [Tables support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Using data tables]: ../../reference/data-tables.md#using-data-tables
   [Column alignment]: ../../reference/data-tables.md#column-alignment
 
@@ -325,26 +327,26 @@ should be considered.
 ### Fenced Code Blocks
 
 [:octicons-workflow-24: Extension][Fenced Code Blocks] ·
-[:octicons-tag-24: 0.1.0 – present][Fenced Code Blocks added]
+[:octicons-tag-24: 0.1.0 – present][Fenced Code Blocks support]
 
 Superseded by [SuperFences]. This extension might still work, but the
 [SuperFences] extension is superior in many ways, as it allows for arbitrary 
 nesting, and therefore strongly recommended.
 
   [Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
-  [Fenced Code Blocks added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [Fenced Code Blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
 
 ### CodeHilite
 
 [:octicons-workflow-24: Extension][CodeHilite] ·
-[:octicons-tag-24: 0.1.0 – 5.5.14][CodeHilite added]
+[:octicons-tag-24: 0.1.0 – 5.5.14][CodeHilite support]
 
 Superseded by [Highlight]. Support for CodeHilite was dropped in version 6.0.0,
 as [Highlight] has a better integration with other great extensions like 
 [SuperFences] and [InlineHilite].
 
   [CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/
-  [CodeHilite added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [CodeHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
   [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/