diff --git a/docs/setup/extensions/index.md b/docs/setup/extensions/index.md index 0393d2e55..50e46f811 100644 --- a/docs/setup/extensions/index.md +++ b/docs/setup/extensions/index.md @@ -3,4 +3,61 @@ template: overrides/main.html title: Extensions --- -Add minimal example. +# Extensions + +=== "Recommended" + + ``` 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 + ``` + +=== "Minimal" + + ``` yaml + markdown_extensions: + + # Python Markdown + - meta + - toc: + permalink: true + + # Python Markdown Extensions + - pymdownx.highlight + - pymdownx.inlinehilite + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + ``` diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index ff763a93f..dcea5232c 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -4,14 +4,141 @@ template: overrides/main.html # Python Markdown Extensions +The [Python Markdown Extensions] package is an excellent collection of Markdown +extensions that make technical writing a breeze. Material for MkDocs views this +package as a sibling of its own, which is why most provided extensions are +already natively supported. + + [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/ + ## 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 +recommended configuration. + + [Extensions]: index.md + ### Arithmatex +[: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, +and integrates seamlessly with [MathJax][^1], a library for mathematical +typesetting. Enable it via `mkdocs.yml`: + + [^1]: + Other libraries like [KaTeX] are also supported and can be integrated with + some additional effort. See the [Arithmatex documentation on KaTeX] for + further guidance, as this is beyond the scope of Material for MkDocs. + +``` yaml +markdown_extensions: + - pymdownx.arithmatex: + generic: true +``` + +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`" + + ``` js + window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } + }; + + document$.subscribe(() => { + MathJax.typesetPromise() + }) + ``` + +=== "`mkdocs.yml`" + + ``` yaml + extra_javascript: + - javascripts/config.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + ``` + +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. + + [Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/ + [Arithmatex support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 + [Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex + [MathJax]: https://www.mathjax.org/ + [KaTeX]: https://github.com/Khan/KaTeX + [additional JavaScript]: ../../customization.md#additional-javascript + ### Critic +[:octicons-workflow-24: Extension][Critic] · +[: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 +via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - pymdownx.critic +``` + +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 + alternatively `accept` or `reject` them: + + === "View changes" + + ``` yaml + markdown_extensions: + - pymdownx.critic: + mode: view + ``` + + === "Accept changes" + + ``` yaml + markdown_extensions: + - pymdownx.critic: + mode: accept + ``` + + === "Reject changes" + + ``` yaml + markdown_extensions: + - pymdownx.critic: + mode: reject + ``` + + [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 + ### Details +The [Details] extension supercharges the [Admonition] extension, making the +resulting _call-outs_ collapsible, rendering + + ### Emoji ### Highlight diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index 31fc85498..92147f3c3 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -14,16 +14,16 @@ is a list of all supported extensions, linking to the relevant sections of the ## Supported extensions -The following [Python Markdown] extensions are supported by Material for -MkDocs, and are therefore strongly recommended. See the [Extensions] page for -a minimal configuration. +The following extensions are all supported by Material for MkDocs and therefore +strongly recommended. See the [overview][Extensions] page for a minimal and +recommended configuration. [Extensions]: index.md ### Abbreviations [:octicons-workflow-24: Extension][Abbreviations] · -[:octicons-tag-24: 1.0.0 – present][Abbreviations added] +[: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 @@ -40,14 +40,14 @@ No configuration options are available. See reference for usage: - [Adding a glossary] [Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/ - [Abbreviations added]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 + [Abbreviations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 [Adding abbreviations]: ../../reference/abbreviations.md#adding-abbreviations [Adding a glossary]: ../../reference/abbreviations.md#adding-a-glossary ### Admonition [:octicons-workflow-24: Extension][Admonition] · -[:octicons-tag-24: 0.1.0 – present][Admonition added] +[: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 @@ -60,12 +60,14 @@ markdown_extensions: No configuration options are available. See reference for usage: +- [Adding admonitions] - [Changing the title] - [Removing the title] - [Supported types] [Admonition]: https://python-markdown.github.io/extensions/admonition/ - [Admonition added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Admonition support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Adding admonitions]: ../../reference/admonitions.md#usage [Changing the title]: ../../reference/admonitions.md#changing-the-title [Removing the title]: ../../reference/admonitions.md#removing-the-title [Supported types]: ../../reference/admonitions.md#supported-types @@ -73,7 +75,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 added] +[: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 @@ -92,7 +94,7 @@ No configuration options are available. See reference for usage: - [Image lazy-loading] [Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/ - [Attribute Lists added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Attribute Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations [Adding buttons]: ../../reference/buttons.md#adding-buttons [Adding icons with colors]: ../../reference/buttons.md#with-colors @@ -102,7 +104,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 added] +[: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. @@ -118,14 +120,14 @@ No configuration options are available. See reference for usage: - [Using definition lists] [Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/ - [Definition Lists added]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0 + [Definition Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0 [description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl [Using definition lists]: ../../reference/lists.md#using-definition-lists ### Footnotes [:octicons-workflow-24: Extension][Footnotes] · -[:octicons-tag-24: 1.0.0 – present][Footnotes added] +[: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 @@ -142,14 +144,14 @@ No configuration options are supported. See reference for usage: - [Adding footnote content] [Footnotes]: https://python-markdown.github.io/extensions/footnotes/ - [Footnotes added]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 + [Footnotes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 [Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references [Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content ### Metadata [:octicons-workflow-24: Extension][Metadata] · -[:octicons-tag-24: 1.0.0 – present][Metadata added] +[: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 @@ -168,7 +170,7 @@ No configuration options are available. See reference for usage: - [Adding tags] [Metadata]: https://python-markdown.github.io/extensions/meta_data/ - [Metadata added]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 + [Metadata support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 [Setting the page title]: ../../reference/meta-tags.md#setting-the-page-title [Setting the page description]: ../../reference/meta-tags.md#setting-the-page-description [Hiding the sidebars]: ../../setup/setting-up-navigation.md#hiding-the-sidebars @@ -177,7 +179,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 added] +[: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 @@ -199,13 +201,13 @@ No configuration options are available. See reference for usage: - [Image captions] [Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/ - [Markdown in HTML added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Markdown in HTML support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [Image captions]: ../../reference/images.md#image-captions ### Table of Contents [:octicons-workflow-24: Extension][Table of Contents] · -[:octicons-tag-24: 0.1.0 – present][Table of Contents added] +[:octicons-tag-24: 0.1.0 – present][Table of Contents support] The [Table of Contents] extension generates a table of contents from a Markdown document, which Material for MkDocs will render as part of the resulting page. @@ -289,13 +291,13 @@ The following configuration options are supported: ``` [Table of Contents]: https://python-markdown.github.io/extensions/toc/ - [Table of Contents added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [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/ ### Tables [:octicons-workflow-24: Extension][Tables] · -[:octicons-tag-24: 0.1.0 – present][Tables added] +[:octicons-tag-24: 0.1.0 – present][Tables support] The [Tables] extension adds the ability to create tables in Markdown documents by using a simple syntax. Enabled it via `mkdocs.yml` (albeit it should be @@ -312,7 +314,7 @@ No configuration options are available. See reference for usage: - [Column alignment] [Tables]: https://python-markdown.github.io/extensions/tables/ - [Tables added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Tables support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [Using data tables]: ../../reference/data-tables.md#using-data-tables [Column alignment]: ../../reference/data-tables.md#column-alignment @@ -325,26 +327,26 @@ should be considered. ### Fenced Code Blocks [:octicons-workflow-24: Extension][Fenced Code Blocks] · -[:octicons-tag-24: 0.1.0 – present][Fenced Code Blocks added] +[: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 nesting, and therefore strongly recommended. [Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/ - [Fenced Code Blocks added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Fenced Code Blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ ### CodeHilite [:octicons-workflow-24: Extension][CodeHilite] · -[:octicons-tag-24: 0.1.0 – 5.5.14][CodeHilite added] +[: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 [SuperFences] and [InlineHilite]. [CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/ - [CodeHilite added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [CodeHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/