Updated Extension documentation

2024-11-12 01:50:52 +01:00 · 2021-10-03 14:54:22 +02:00 · 2021-10-03 14:54:22 +02:00 · 8e527be8b2
commit 8e527be8b2
parent 4b433536c5
3 changed files with 253 additions and 79 deletions
--- a/docs/setup/extensions/index.md
+++ b/docs/setup/extensions/index.md
@ -5,56 +5,137 @@ title: Extensions

 # Extensions

-=== "Recommended"
+Markdown is a very small language with a kind-of reference implementation called
+[John Gruber's Markdown]. [Python Markdown] and [Python Markdown Extensions]
+are two packages that enhance the Markdown writing experience, adding useful
+syntax extensions for technical writing.

-    ``` yaml
-    markdown_extensions:
+  [John Gruber's Markdown]: https://daringfireball.net/projects/markdown/
+  [Python Markdown]: #python-markdown.md
+  [Python Markdown Extensions]: #python-markdown-extensions.md

-      # Python Markdown
-      - abbr
-      - admonition
-      - attr_list
-      - def_list
-      - footnotes
-      - meta
-      - md_in_html
-      - toc:
-          permalink: true
+## Supported extensions

-      # 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
-    ```
+The following extensions are all supported by Material for MkDocs and therefore _strongly recommended_. Click on each extension to learn about its purpose and
+configuration:

-=== "Minimal"
+<div class="mdx-columns" markdown="1">

-    ``` yaml
-    markdown_extensions:
+- [Abbreviations]
+- [Admonition]
+- [Arithmatex]
+- [Attribute Lists]
+- [BetterEm]
+- [Caret, Mark & Tilde]
+- [Critic]
+- [Definition Lists]
+- [Details]
+- [Emoji]
+- [Footnotes]
+- [Highlight]
+- [Keys]
+- [Metadata]
+- [Markdown in HTML]
+- [SmartSymbols]
+- [Snippets]
+- [SuperFences]
+- [Tabbed]
+- [Table of Contents]
+- [Tables]
+- [Tasklist]

-      # Python Markdown
-      - meta
-      - toc:
-          permalink: true
+</div>

-      # Python Markdown Extensions
-      - pymdownx.highlight
-      - pymdownx.superfences
-    ```
+  [Abbreviations]: python-markdown.md#abbreviations
+  [Admonition]: python-markdown.md#admonition
+  [Arithmatex]: python-markdown-extensions.md#arithmatex
+  [Attribute Lists]: python-markdown.md#attribute-lists
+  [BetterEm]: python-markdown-extensions.md#betterem
+  [Caret, Mark & Tilde]: python-markdown-extensions.md#caret-mark-tilde
+  [Critic]: python-markdown-extensions.md#critic
+  [Definition Lists]: python-markdown.md#definition-lists
+  [Details]: python-markdown-extensions.md#details
+  [Emoji]: python-markdown-extensions.md#emoji
+  [Footnotes]: python-markdown.md#footnotes
+  [Highlight]: python-markdown-extensions.md#highlight
+  [Keys]: python-markdown-extensions.md#keys
+  [Metadata]: python-markdown.md#metadata
+  [Markdown in HTML]: python-markdown.md#markdown-in-html
+  [SmartSymbols]: python-markdown-extensions.md#smartsymbols
+  [Snippets]: python-markdown-extensions.md#snippets
+  [SuperFences]: python-markdown-extensions.md#superfences
+  [Tabbed]: python-markdown-extensions.md#tabbed
+  [Table of Contents]: python-markdown.md#table-of-contents
+  [Tables]: python-markdown.md#tables
+  [Tasklist]: python-markdown-extensions.md#tasklist
+
+## Configuration
+
+Extensions are configured as part of `mkdocs.yml` – the MkDocs configuration
+file. The following sections contain two example configurations to bootstrap
+your documentation project.
+
+  [overview]: #advanced-configuration
+
+### Minimal configuration
+
+The minimal configuration is a good starting point for when you're using
+Material for MkDocs for the first time. The best idea is to explore the
+[reference], and gradually add what you want to use:
+
+``` yaml
+markdown_extensions:
+
+  # Python Markdown
+  - meta
+  - toc:
+      permalink: true
+
+  # Python Markdown Extensions
+  - pymdownx.highlight
+  - pymdownx.superfences
+```
+
+  [reference]: ../../reference/abbreviations.md
+
+### Recommended configuration
+
+The recommended configuration enables all Markdown-related features of Material
+for MkDocs and is great for bootstrapping a new documentation project:
+
+``` 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
+```
--- a/docs/setup/extensions/python-markdown-extensions.md
+++ b/docs/setup/extensions/python-markdown-extensions.md
@ -22,10 +22,10 @@ recommended configuration.
 ### Arithmatex

 [:octicons-workflow-24: Extension][Arithmatex] ·
-[:octicons-tag-24: 1.0.0 – present][Arithmatex support]
+[:octicons-tag-24: 1.0.0 ... present][Arithmatex support]

 The [Arithmatex] extension allows for rendering of block and inline block
-equations, and integrates seamlessly with [MathJax][^1], a library for
+equations, and integrates seamlessly with [MathJax][^1] – a library for
 mathematical typesetting. Enable it via `mkdocs.yml`:

  [^1]:
@ -91,10 +91,63 @@ See reference for usage:
  [Using block syntax]: ../../reference/mathjax.md#using-block-syntax
  [Using inline block syntax]: ../../reference/mathjax.md#using-inline-block-syntax

+### BetterEm
+
+[:octicons-workflow-24: Extension][BetterEm] ·
+[:octicons-tag-24: 0.1.0 ... present][BetterEm support]
+
+The [BetterEm] extension improves the detection of Markup to emphasize text
+in Markdown using special characters, i.e. for `**bold**` and `_italic_`
+formatting. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.betterem
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm 
+documentation][BetterEm] for more information.
+
+  [BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
+  [BetterEm support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+
+### Caret, Mark & Tilde
+
+[:octicons-workflow-24: Extension][Caret] ·
+[:octicons-tag-24: 1.0.0 ... present][Caret support]
+
+The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text
+and define sub- and superscript using a simple syntax. Enable them together
+via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.caret
+  - pymdownx.mark
+  - pymdownx.tilde
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [Caret], [Mark]
+and [Tilde documentation][Tilde] for guidance.
+
+See reference for usage:
+
+- [Highlighting text]
+- [Sub- and superscripts]
+
+  [Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
+  [Caret support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
+  [Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
+  [Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
+  [Highlighting text]: ../../reference/formatting.md#highlighting-text
+  [Sub- and superscripts]: ../../reference/formatting.md#sub-and-superscripts
+
 ### Critic

 [:octicons-workflow-24: Extension][Critic] ·
-[:octicons-tag-24: 1.0.0 – present][Critic support]
+[: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 document, i.e. for tracking changes in
@ -149,7 +202,7 @@ See reference for usage:
 ### Details

 [:octicons-workflow-24: Extension][Details] ·
-[:octicons-tag-24: 1.9.0 – present][Details support]
+[: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
@ -172,7 +225,7 @@ No configuration options are available. See reference for usage:
 ### Emoji

 [:octicons-workflow-24: Extension][Emoji] ·
-[:octicons-tag-24: 1.0.0 – present][Emoji support]
+[: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`:
@ -251,7 +304,7 @@ See reference for usage:
 ### Highlight

 [:octicons-workflow-24: Extension][Highlight] ·
-[:octicons-tag-24: 5.0.0 – present][Highlight support] ·
+[: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
@ -380,7 +433,7 @@ See reference for usage:
 ### InlineHilite

 [:octicons-workflow-24: Extension][InlineHilite] ·
-[:octicons-tag-24: 5.0.0 – present][InlineHilite support]
+[: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
@ -392,19 +445,68 @@ markdown_extensions:
  - pymdownx.inlinehilite
 ```

-No configuration options are supported. See reference for usage:
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. The only exception is
+the [`css_class`][InlineHilite options] option, which must not be changed. See the 
+[InlineHilite documentation][InlineHilite] for guidance.
+
+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
+  [InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options
  [Highlight #]: #highlight
  [Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks

+### Keys
+
+[:octicons-workflow-24: Extension][Keys] ·
+[:octicons-tag-24: 1.0.0 ... present][Keys support]
+
+The [Keys] extension adds a simple syntax to allow for the rendering of keyboard 
+keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.keys
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. The only exception is
+the [`class`][Keys options] option, which must not be changed. See the 
+[Keys documentation][Keys] for more information.
+
+  [Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
+  [Keys support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
+  [Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options
+
+### SmartSymbols
+
+[:octicons-workflow-24: Extension][SmartSymbols] ·
+[:octicons-tag-24: 0.1.0 ... present][SmartSymbols support]
+
+The [SmartSymbols] extension converts some sequences of characters into their 
+corresponding symbols, e.h. copyright symbols or fractions. Enable it via
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.smartsymbols
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols 
+documentation][SmartSymbols] for guidance.
+
+  [SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
+  [SmartSymbols support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+
 ### Snippets

 [:octicons-workflow-24: Extension][Snippets] ·
-[:octicons-tag-24: 0.1.0 – present][Snippets support]
+[: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
@ -430,7 +532,7 @@ See reference for usage:
 ### SuperFences

 [:octicons-workflow-24: Extension][SuperFences] ·
-[:octicons-tag-24: 5.0.0 – present][SuperFences support] ·
+[: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
@ -489,7 +591,7 @@ See reference for usage:
 ### Tabbed

 [:octicons-workflow-24: Extension][Tabbed] ·
-[:octicons-tag-24: 5.0.0 – present][Tabbed support]
+[: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
@ -538,7 +640,7 @@ See reference for usage:
 ### Tasklist

 [:octicons-workflow-24: Extension][Tasklist] ·
-[:octicons-tag-24: 1.0.0 – present][Tasklist support]
+[: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
@ -590,12 +692,3 @@ See reference for usage:
  [Tasklist #]: #tasklist
  [Spec]: https://github.github.com/gfm/#task-list-items-extension-
  [Using task lists]: ../../reference/lists.md#using-task-lists
-
-### Other
-
- Caret
- Keys
- MagicLink
- Mark
- SmartSymbols
- Tilde
--- a/docs/setup/extensions/python-markdown.md
+++ b/docs/setup/extensions/python-markdown.md
@ -22,10 +22,10 @@ recommended configuration.
 ### Abbreviations

 [:octicons-workflow-24: Extension][Abbreviations] ·
-[:octicons-tag-24: 1.0.0 – present][Abbreviations support]
+[: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
+element, by wrapping it with an `abbr` tag. Only plain text (no markup) is
 supported. Enable it via `mkdocs.yml`:

 ``` yaml
@ -46,7 +46,7 @@ No configuration options are available. See reference for usage:
 ### Admonition

 [:octicons-workflow-24: Extension][Admonition] ·
-[:octicons-tag-24: 0.1.0 – present][Admonition support]
+[: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 defined in Markdown by using a simple syntax. Enable
@ -74,7 +74,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 support]
+[: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
@ -103,7 +103,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 support]
+[: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) via Markdown to a
@ -126,7 +126,7 @@ No configuration options are available. See reference for usage:
 ### Footnotes

 [:octicons-workflow-24: Extension][Footnotes] ·
-[:octicons-tag-24: 1.0.0 – present][Footnotes support]
+[: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 Markdown content of a document. Enable it
@ -150,7 +150,7 @@ No configuration options are supported. See reference for usage:
 ### Metadata

 [:octicons-workflow-24: Extension][Metadata] ·
-[:octicons-tag-24: 1.0.0 – present][Metadata support]
+[:octicons-tag-24: 1.0.0 ... present][Metadata support]

 The [Metadata] extension adds the ability to attach arbitrary key-value pairs
 to a document via front matter written in YAML syntax before the Markdown. It
@ -178,7 +178,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 support]
+[: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
@ -206,7 +206,7 @@ No configuration options are available. See reference for usage:
 ### Table of Contents

 [:octicons-workflow-24: Extension][Table of Contents] ·
-[:octicons-tag-24: 0.1.0 – present][Table of Contents support]
+[:octicons-tag-24: 0.1.0 ... present][Table of Contents support]

 The [Table of Contents] extension automatically generates a table of contents
 from a document, which Material for MkDocs will render as part of the resulting 
@ -300,7 +300,7 @@ own risk.
 ### Tables

 [:octicons-workflow-24: Extension][Tables] ·
-[:octicons-tag-24: 0.1.0 – present][Tables support]
+[:octicons-tag-24: 0.1.0 ... present][Tables support]

 The [Tables] extension adds the ability to create tables in Markdown by using a 
 simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
@ -330,7 +330,7 @@ should be considered.
 ### Fenced Code Blocks

 [:octicons-workflow-24: Extension][Fenced Code Blocks] ·
-[:octicons-tag-24: 0.1.0 – present][Fenced Code Blocks support]
+[: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 
@ -343,7 +343,7 @@ nesting, and therefore strongly recommended.
 ### CodeHilite

 [:octicons-workflow-24: Extension][CodeHilite] ·
-[:octicons-tag-24: 0.1.0 – 5.5.14][CodeHilite support]
+[: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 essential extensions like