diff --git a/docs/setup/extensions/index.md b/docs/setup/extensions/index.md
index 5b5e5b288..40b826459 100644
--- 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"
+
- ``` 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
+
- # 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
+```
diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md
index 8b56f4793..24ea9c63f 100644
--- 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
diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md
index 88a2e9c05..82e50317b 100644
--- 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