Updated extension documentation

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

@@ -4,10 +4,10 @@ template: overrides/main.html
 
 # Python Markdown Extensions
 
-The [Python Markdown Extensions] package is an excellent collection of Markdown
+The [Python Markdown Extensions] package is an excellent collection of
-extensions that make technical writing a breeze. Material for MkDocs views this 
+additional Markdown extensions that make technical writing a breeze. Material
-package as a sibling of its own, which is why most provided extensions are
+for MkDocs lists this package as an explicit dependency, so it's automatically
-already natively supported.
+installed with a supported version.
 
   [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
 
@@ -24,9 +24,9 @@ recommended configuration.
 [: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,
+The [Arithmatex] extension allows for rendering of block and inline block
-and integrates seamlessly with [MathJax][^1], a library for mathematical
+equations, and integrates seamlessly with [MathJax][^1], a library for
-typesetting. Enable it via `mkdocs.yml`:
+mathematical typesetting. Enable it via `mkdocs.yml`:
 
   [^1]:
     Other libraries like [KaTeX] are also supported and can be integrated with
@@ -43,7 +43,7 @@ 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`"
+=== ":octicons-file-code-16: docs/javascripts/config.js"
 
     ``` js
     window.MathJax = {
@@ -64,7 +64,7 @@ of [additional JavaScript]:
     })
     ```
 
-=== "`mkdocs.yml`"
+=== ":octicons-file-code-16: mkdocs.yml"
 
     ``` yaml
     extra_javascript:
@@ -74,7 +74,12 @@ of [additional JavaScript]:
     ```
 
 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.
+MkDocs might not provide native support. See the [Arithmatex documentation][Arithmatex] for more information.
+
+See reference for usage:
+
+- [Using block syntax]
+- [Using inline block syntax]
 
   [Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
   [Arithmatex support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
@@ -82,6 +87,8 @@ MkDocs  might not provide native support. See the [Arithmatex documentation][Ari
   [MathJax]: https://www.mathjax.org/
   [KaTeX]: https://github.com/Khan/KaTeX
   [additional JavaScript]: ../../customization.md#additional-javascript
+  [Using block syntax]: ../../reference/mathjax.md#using-block-syntax
+  [Using inline block syntax]: ../../reference/mathjax.md#using-inline-block-syntax
 
 ### Critic
 
@@ -89,8 +96,8 @@ MkDocs  might not provide native support. See the [Arithmatex documentation][Ari
 [: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
+added, deleted or updated sections in a Markdown document, e.g. for tracking 
-via `mkdocs.yml`:
+changes. Enable it via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -102,7 +109,7 @@ 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
+    should be parsed, i.e. whether to just `view` all suggested changes, or
     alternatively `accept` or `reject` them:
 
     === "View changes"
@@ -129,26 +136,272 @@ The following configuration options are supported:
               mode: reject
         ```
 
+See reference for usage:
+
+- [Highlighting changes]
+
   [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
+  [Highlighting changes]: ../../reference/formatting.md#highlighting-changes
 
 ### Details
 
-The [Details] extension supercharges the [Admonition] extension, making the
+[:octicons-workflow-24: Extension][Details] ·
-resulting _call-outs_ collapsible, rendering
+[:octicons-tag-24: 1.9.0 – present][Details support]
 
+The [Details] extension supercharges the [Admonition] extension, making the
+resulting _call-outs_ collapsible, allowing them to be opened and closed by the
+user. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.details
+```
+
+No configuration options are available. See reference for usage:
+
+- [Collapsible blocks]
+
+  [Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
+  [Details support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.9.0
+  [Admonition]: python-markdown.md#admonition
+  [Collapsible blocks]: ../../reference/admonitions.md#collapsible-blocks
 
 ### Emoji
 
+[:octicons-workflow-24: Extension][Emoji] ·
+[:octicons-tag-24: 1.0.0 – present][Emoji support]
+
+The [Emoji] extension automatically inlines bundled and custom icons and emojis
+in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji # (1)
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+```
+
+1.  [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to
+    support the inlining of icons, the `materialx` namespace must be used, as it
+    extends the functionality of `pymdownx`.
+
+The following configuration options are supported:
+
+`emoji_index`{ #emoji_index }
+
+:   :octicons-milestone-24: Default: `emojione` – This option defines which set
+    of emojis is used for rendering. Note that the use of `emojione` is not
+    recommended due to [restrictions in licensing][Emoji index]:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.emoji:
+          emoji_index: !!python/name:materialx.emoji.twemoji
+    ```
+
+`emoji_generator`{ #emoji_generator }
+
+:   :octicons-milestone-24: Default: `to_png` – This option defines how the
+    resolved emoji or icon shortcode is render. Note that icons can only be
+    used together with the `to_svg` configuration:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.emoji:
+          emoji_generator: !!python/name:materialx.emoji.to_svg
+    ```
+
+`options.custom_icons`{ #custom_icons }
+
+:   :octicons-milestone-24: Default: _none_ – This option allows to list folders
+    with additional icon sets to be used in Markdown documents, which is 
+    explained in more detail in the [icon customization guide].
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.emoji:
+          emoji_index: !!python/name:materialx.emoji.twemoji
+          emoji_generator: !!python/name:materialx.emoji.to_svg
+          options:
+            custom_icons:
+              - overrides/.icons
+    ```
+
+See reference for usage:
+
+- [Using emojis]
+- [Using icons]
+- [Using icons in templates]
+
+  [Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
+  [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
+  [Using emojis]: ../../reference/icons-emojis.md#using-emojis
+  [Using icons]: ../../reference/icons-emojis.md#using-icons
+  [Using icons in templates]: ../../reference/icons-emojis.md#using-icons-in-templates
+
 ### Highlight
 
+[:octicons-workflow-24: Extension][Highlight] ·
+[:octicons-tag-24: 5.0.0 – present][Highlight support] ·
+:octicons-zap-24: Supersedes [CodeHilite]
+
+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
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences # (1)
+```
+
+1.  [Highlight] is used by the [SuperFences][SuperFences #] extension to
+    perform syntax highlighting on code blocks, not the other way round, which
+    is why this extension also needs to be enabled.
+
+    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.
+
+The following configuration options are supported:
+
+`use_pygments`{ #use-pygments }
+
+:   :octicons-milestone-24: Default: `true` – This option allows to control
+    whether highlighting should be carried out during build time using
+    [Pygments] or runtime with a JavaScript syntax highlighter:
+
+    === "Pygments"
+
+        ``` yaml
+        markdown_extensions:
+          - pymdownx.highlight:
+              use_pygments: true
+          - pymdownx.superfences
+        ```
+
+    === "JavaScript"
+
+        ``` yaml
+        markdown_extensions:
+          - pymdownx.highlight:
+              use_pygments: false
+        ```
+
+        As an example, [Highlight.js], a JavaScript syntax highlighter, can be 
+        integrated with some [additional JavaScript] and [CSS][additional CSS]
+        in `mkdocs.yml`:
+
+        === ":octicons-file-code-16: docs/javascripts/config.js"
+
+            ``` js
+            document$.subscribe(() => {
+              hljs.highlightAll()
+            })
+            ```
+
+        === ":octicons-file-code-16: mkdocs.yml"
+
+            ``` yaml
+            extra_javascript:
+              - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
+              - javascripts/config.js
+            extra_css:
+              - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
+            ```
+
+        Note that [Highlight.js] has no affiliation with the Highlight extension.
+
+`linenums`{ #linenums }
+
+:   :octicons-milestone-24: Default: `false` – This option will add line numbers
+    to _all_ code blocks. If you wish to add line numbers to _some_, but not all
+    code blocks, consult the section on [adding line numbers][Adding line
+    numbers] in the code block reference, which also contains some tips on
+    working with line numbers:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.highlight:
+          linenums: true
+    ```
+
+`linenums_style`{ #linenums-style }
+
+:   :octicons-milestone-24: Default: `table` – The [Highlight] extension
+    provides three ways to add line numbers, all of which are supported by
+    Material for MkDocs. While `table` wraps a code block in a table, `inline`
+    and `pymdownx-inline` render line numbers as part of the line itself:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.highlight:
+          linenums_style: pymdownx-inline
+    ```
+
+    Note that `inline` will put line numbers next to the actual code, which
+    means that they will be included when selecting text with the cursor or 
+    copying a code block to the clipboard. Thus, the usage of either `table`
+    or `pymdownx-inline` is recommended.
+
+See reference for usage:
+
+- [Specifying the language]
+- [Adding line numbers]
+- [Highlighting specific lines]
+- [Custom syntax theme]
+
+  [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
+  [Highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
+  [CodeHilite]: python-markdown.md#codehilite
+  [SuperFences #]: #superfences
+  [InlineHilite #]: #inlinehilite
+  [Pygments]: https://pygments.org
+  [additional CSS]: ../../customization.md#additional-css
+  [Highlight.js]: https://highlightjs.org/
+  [Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
+  [Specifying the language]: ../../reference/code-blocks.md#specifying-the-language
+  [Highlighting specific lines]: ../../reference/code-blocks.md#highlighting-specific-lines
+  [Custom syntax theme]: ../../reference/code-blocks.md#custom-syntax-theme
+
 ### InlineHilite
 
+[:octicons-workflow-24: Extension][InlineHilite] ·
+[:octicons-tag-24: 5.0.0 – present][InlineHilite support]
+
+The [InlineHilite] extension add support for syntax highlighting of inline code 
+blocks. It's built on top of the [Highlight][Highlight #] extension, from which
+it sources its configuration. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+```
+
+No configuration options are supported. See reference for usage:
+
+- [Highlighting inline code blocks]
+
+  [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
+  [InlineHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
+  [Highlight #]: #highlight
+  [Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
+
 ### Snippets
 
+[:octicons-workflow-24: Extension][Snippets] ·
+[:octicons-tag-24: 0.1.0 – present][Snippets support]
+
 ### SuperFences
 
+TODO: document Mermaid setup!
+
 ### Tabbed
 
 ### Tasklist

docs/setup/extensions/python-markdown.md

@@ -7,10 +7,9 @@ template: overrides/main.html
 Material for MkDocs supports a large number of [Python Markdown] extensions,
 which is part of what makes it so attractive for technical writing. Following
 is a list of all supported extensions, linking to the relevant sections of the
-[reference] for what features they need to be enabled.
+reference for what features they need to be enabled.
 
   [Python Markdown]: https://python-markdown.github.io/
-  [reference]: ../../reference/abbreviations.md
 
 ## Supported extensions
 
@@ -107,7 +106,7 @@ 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) to any Markdown document.
 Enable it via `mkdocs.yml`:
 
 ``` yaml
@@ -249,7 +248,7 @@ The following configuration options are supported:
 :   :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
     customization of the slug function. For some languages, the default may not
     produce good and readable identifiers – consider using another slug function
-    like for example those from [Python Markdown Extensions][Pymdownx Slug]:
+    like for example those from [Python Markdown Extensions][Pymdownx slug]:
 
     === "Unicode"
 
@@ -292,7 +291,7 @@ The following configuration options are supported:
 
   [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/
+  [Pymdownx slug]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
 
 ### Tables
 
@@ -343,7 +342,7 @@ nesting, and therefore strongly recommended.
 [: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 
+as [Highlight] has a better integration with other essential extensions like 
 [SuperFences] and [InlineHilite].
 
   [CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/