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