Updated Python Markdown Extensions documentation

docs/reference/lists.md

@@ -173,7 +173,7 @@ _Result_:
 
   [6]: #definition-list
 
-### Using tasklists
+### Using task lists
 
 When the [Tasklist][7] extension is enabled, unordered list items can be
 prefixed with `[ ]` to render an unchecked or `[x]` to render a checked

docs/setup/extensions/index.md

@@ -56,8 +56,5 @@ title: Extensions
 
       # Python Markdown Extensions
       - pymdownx.highlight
-      - pymdownx.inlinehilite
       - pymdownx.superfences
-      - pymdownx.tabbed:
-          alternate_style: true
     ```

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

@@ -14,7 +14,7 @@ installed with a supported version.
 ## 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
+_strongly recommended_. See the [overview][Extensions] page for a minimal and
 recommended configuration.
 
   [Extensions]: index.md
@@ -73,8 +73,9 @@ of [additional JavaScript]:
       - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
     ```
 
-Arithmatex can be configured in many different ways, for which Material for
+The other configuration options of this extension are not officially supported
-MkDocs might not provide native support. See the [Arithmatex documentation][Arithmatex] for more information.
+by Material for MkDocs, so they may yield unexpected results. Use them at your
+own risk.
 
 See reference for usage:
 
@@ -96,8 +97,8 @@ See reference for usage:
 [:octicons-tag-24: 1.0.0 – present][Critic support]
 
 The [Critic] extension allows for the usage of [Critic Markup] to highlight
-added, deleted or updated sections in a Markdown document, e.g. for tracking 
+added, deleted or updated sections in a document, i.e. for tracking changes in
-changes. Enable it via `mkdocs.yml`:
+Markdown syntax. Enable it via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -229,13 +230,17 @@ The following configuration options are supported:
               - overrides/.icons
     ```
 
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, so they may yield unexpected results. Use them at your
+own risk.
+
 See reference for usage:
 
 - [Using emojis]
 - [Using icons]
 - [Using icons in templates]
 
-  [Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
+  [Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
   [Emoji support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
   [icon customization guide]: ../changing-the-logo-and-icons.md#additional-icons
@@ -251,8 +256,7 @@ See reference for usage:
 
 The [Highlight] extension adds support for syntax highlighting of code blocks
 (with the help of [SuperFences][SuperFences #]) and inline code blocks (with
-the help of [InlineHilite][InlineHilite #]). Enable it via
+the help of [InlineHilite][InlineHilite #]). Enable it via `mkdocs.yml`:
-`mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -266,7 +270,7 @@ markdown_extensions:
 
     However, this only applies for when [Pygments] is used. If you use a
     JavaScript syntax highlighter, [SuperFences][SuperFences #] might not
-    be necessary, but it's strongly recommended anyway.
+    be necessary, but it's _strongly recommended_ anyway.
 
 The following configuration options are supported:
 
@@ -349,6 +353,10 @@ The following configuration options are supported:
     copying a code block to the clipboard. Thus, the usage of either `table`
     or `pymdownx-inline` is recommended.
 
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, so they may yield unexpected results. Use them at your
+own risk.
+
 See reference for usage:
 
 - [Specifying the language]
@@ -398,14 +406,191 @@ No configuration options are supported. See reference for usage:
 [:octicons-workflow-24: Extension][Snippets] ·
 [:octicons-tag-24: 0.1.0 – present][Snippets support]
 
+The [Snippets] extension adds the ability to embed content from arbitrary files
+into a document, including other documents or source files, by using a simple
+syntax. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.snippets
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [Snippets 
+documentation][Snippets] for more information.
+
+See reference for usage:
+
+- [Embedding external files]
+
+  [Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
+  [Snippets support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [Embedding external files]: ../../reference/code-blocks.md#embedding-external-files
+
 ### SuperFences
 
-TODO: document Mermaid setup!
+[:octicons-workflow-24: Extension][SuperFences] ·
+[:octicons-tag-24: 5.0.0 – present][SuperFences support] ·
+:octicons-zap-24: Supersedes [Fenced Code Blocks]
+
+The [SuperFences] extension allows for arbitrary nesting of code and content
+blocks inside each other, including admonitions, tabs, lists and all other
+elements. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.superfences
+```
+
+The following configuration options are supported:
+
+`custom_fences`{ #custom_fences }
+
+:   :octicons-milestone-24: Default: _none_ – This option allows to define a
+    handler for custom fences, e.g. to preserve the definitions of [Mermaid.js]
+    diagrams to be interpreted in the browser:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.superfences:
+          custom_fences:
+            - name: mermaid
+              class: mermaid
+              format: !!python/name:pymdownx.superfences.fence_code_format
+    ```
+
+    Note that this will primarily prevent syntax highlighting from being
+    applied. See the reference on [diagrams] to learn how Mermaid.js is
+    integrated with Material for MkDocs.
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, so they may yield unexpected results. Use them at your
+own risk.
+
+See reference for usage:
+
+- [Using flowcharts]
+- [Using sequence diagrams]
+- [Using state diagrams]
+- [Using class diagrams]
+- [Using entity-relationship diagrams]
+
+  [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+  [SuperFences support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+  [Fenced Code Blocks]: python-markdown.md#fenced-code-blocks
+  [Mermaid.js]: https://mermaid-js.github.io/mermaid/
+  [diagrams]: ../../reference/diagrams.md
+  [Using flowcharts]: ../../reference/diagrams.md#using-flowcharts
+  [Using sequence diagrams]: ../../reference/diagrams.md#using-sequence-diagrams
+  [Using state diagrams]: ../../reference/diagrams.md#using-state-diagrams
+  [Using class diagrams]: ../../reference/diagrams.md#using-class-diagrams
+  [Using entity-relationship diagrams]: ../../reference/diagrams.md#using-entity-relationship-diagrams
 
 ### Tabbed
 
+[:octicons-workflow-24: Extension][Tabbed] ·
+[:octicons-tag-24: 5.0.0 – present][Tabbed support]
+
+The [Tabbed] extension allows the usage of content tabs, a simple way to group
+related content and code blocks under accessible tabs. Enable it via
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.tabbed:
+      alternate_style: true 
+```
+
+The following configuration options are supported:
+
+`alternate_style`{ #alternate_style }
+
+:   :octicons-milestone-24: Default: `false` · [:octicons-tag-24: 7.3.1]
+    [Tabbed alternate support] – This option enables the [alternate style] of
+    content tabs, which has [better behavior on smaller screen sizes], and thus
+    is _strongly recommended_:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.tabbed:
+          alternate_style: true 
+    ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, so they may yield unexpected results. Use them at your
+own risk.
+
+See reference for usage:
+
+- [Grouping code blocks]
+- [Grouping other content]
+- [Embedded content]
+
+  [Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
+  [Tabbed support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
+  [Tabbed alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.1
+  [alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
+  [better behavior on smaller screen sizes]: https://twitter.com/squidfunk/status/1424740370596958214
+  [Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
+  [Grouping other content]: ../../reference/content-tabs.md#grouping-other-content
+  [Embedded content]: ../../reference/content-tabs.md#embedded-content
+
 ### Tasklist
 
+[:octicons-workflow-24: Extension][Tasklist] ·
+[:octicons-tag-24: 1.0.0 – present][Tasklist support]
+
+The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
+inspired [task lists][Spec], following the same syntactical conventions. Enable
+it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.tasklist:
+      custom_checkbox: true
+```
+
+The following configuration options are supported:
+
+`custom_checkbox`{ #custom-checkbox }
+
+:   :octicons-milestone-24: Default: `false` · This option toggles the rendering
+    style of checkboxes, replacing native checkbox styles with beautiful icons, 
+    and is therefore _strongly recommended_:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.tasklist:
+          custom_checkbox: true
+    ```
+
+`clickable_checkbox`{ #clickable-checkbox }
+
+:   :octicons-milestone-24: Default: `false` · This option toggles whether
+    checkboxes are clickable. As the state is not persisted, the use of this 
+    option is _rather discouraged_ from a user experience perspective:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.tasklist:
+          clickable_checkbox: true
+    ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, so they may yield unexpected results. Use them at your
+own risk.
+
+See reference for usage:
+
+- [Using task lists]
+
+  [Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
+  [Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
+  [GitHub Flavored Markdown]: https://github.github.com/gfm/
+  [Tasklist #]: #tasklist
+  [Spec]: https://github.github.com/gfm/#task-list-items-extension-
+  [Using task lists]: ../../reference/lists.md#using-task-lists
+
 ### Other
 
 - Caret

docs/setup/extensions/python-markdown.md

@@ -14,7 +14,7 @@ reference for what features they need to be enabled.
 ## 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
+_strongly recommended_. See the [overview][Extensions] page for a minimal and
 recommended configuration.
 
   [Extensions]: index.md
@@ -49,8 +49,8 @@ No configuration options are available. See reference for usage:
 [: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
+_call-outs_, which can be defined in Markdown by using a simple syntax. Enable
-via `mkdocs.yml`:
+it via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -106,8 +106,8 @@ No configuration options are available. See reference for usage:
 [: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.
+commonly known as [description lists] – `dl` in HTML) via Markdown to a
-Enable it via `mkdocs.yml`:
+document. Enable it via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -129,7 +129,7 @@ No configuration options are available. See reference for usage:
 [: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
+which are then rendered after the Markdown content of a document. Enable it
 via `mkdocs.yml`:
 
 ``` yaml
@@ -153,8 +153,8 @@ No configuration options are supported. See reference for usage:
 [: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
+to a document via front matter written in YAML syntax before the Markdown. It
-enabled via `mkdocs.yml`:
+can be enabled via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -208,9 +208,9 @@ No configuration options are available. See reference for usage:
 [:octicons-workflow-24: Extension][Table of Contents] ·
 [:octicons-tag-24: 0.1.0 – present][Table of Contents support]
 
-The [Table of Contents] extension generates a table of contents from a Markdown
+The [Table of Contents] extension automatically generates a table of contents
-document, which Material for MkDocs will render as part of the resulting page.
+from a document, which Material for MkDocs will render as part of the resulting 
-Enable it via `mkdocs.yml`:
+page. Enable it via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -289,6 +289,10 @@ The following configuration options are supported:
               toc_depth: 0
         ```
 
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, so they may yield unexpected results. Use them at your
+own risk.
+
   [Table of Contents]: https://python-markdown.github.io/extensions/toc/
   [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/
@@ -298,9 +302,9 @@ The following configuration options are supported:
 [:octicons-workflow-24: Extension][Tables] ·
 [:octicons-tag-24: 0.1.0 – present][Tables support]
 
-The [Tables] extension adds the ability to create tables in Markdown documents
+The [Tables] extension adds the ability to create tables in Markdown by using a 
-by using a simple syntax. Enabled it via `mkdocs.yml` (albeit it should be
+simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
-enabled by default):
+default):
 
 ``` yaml
 markdown_extensions: