From 30943cc629c49a07fc089add4bfb22c69dbda430 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 2 Oct 2021 19:08:50 +0200 Subject: [PATCH 01/18] Added documentation for Python Markdown --- docs/setup/extensions/index.md | 6 + .../extensions/python-markdown-extensions.md | 36 ++ docs/setup/extensions/python-markdown.md | 350 ++++++++++++++++++ mkdocs.yml | 4 + 4 files changed, 396 insertions(+) create mode 100644 docs/setup/extensions/index.md create mode 100644 docs/setup/extensions/python-markdown-extensions.md create mode 100644 docs/setup/extensions/python-markdown.md diff --git a/docs/setup/extensions/index.md b/docs/setup/extensions/index.md new file mode 100644 index 000000000..0393d2e55 --- /dev/null +++ b/docs/setup/extensions/index.md @@ -0,0 +1,6 @@ +--- +template: overrides/main.html +title: Extensions +--- + +Add minimal example. diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md new file mode 100644 index 000000000..ff763a93f --- /dev/null +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -0,0 +1,36 @@ +--- +template: overrides/main.html +--- + +# Python Markdown Extensions + +## Supported extensions + +### Arithmatex + +### Critic + +### Details + +### Emoji + +### Highlight + +### InlineHilite + +### Snippets + +### SuperFences + +### Tabbed + +### Tasklist + +### Other + +- Caret +- Keys +- MagicLink +- Mark +- SmartSymbols +- Tilde diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md new file mode 100644 index 000000000..31fc85498 --- /dev/null +++ b/docs/setup/extensions/python-markdown.md @@ -0,0 +1,350 @@ +--- +template: overrides/main.html +--- + +# Python Markdown + +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. + + [Python Markdown]: https://python-markdown.github.io/ + [reference]: ../../reference/abbreviations.md + +## 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. + + [Extensions]: index.md + +### Abbreviations + +[:octicons-workflow-24: Extension][Abbreviations] · +[:octicons-tag-24: 1.0.0 – present][Abbreviations added] + +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 +supported. Enable it via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - abbr +``` + +No configuration options are available. See reference for usage: + +- [Adding abbreviations] +- [Adding a glossary] + + [Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/ + [Abbreviations added]: 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] + +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 +via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - admonition +``` + +No configuration options are available. See reference for usage: + +- [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 + [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 + +### Attribute Lists + +[:octicons-workflow-24: Extension][Attribute Lists] · +[:octicons-tag-24: 0.1.0 – present][Attribute Lists added] + +The [Attribute Lists] extension allows to add HTML attributes and CSS classes +to [almost every][Attribute Lists limitations] Markdown inline- and block-level +element with a special syntax. Enable it via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - attr_list +``` + +No configuration options are available. See reference for usage: + +- [Adding buttons] +- [Adding icons with colors] +- [Image alignment] +- [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 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 + [Image alignment]: ../../reference/images.md#image-alignment + [Image lazy-loading]: ../../reference/images.md#image-lazy-loading + +### Definition Lists + +[:octicons-workflow-24: Extension][Definition Lists] · +[:octicons-tag-24: 1.1.0 – present][Definition Lists added] + +The [Definition Lists] extension adds the ability to add definition lists (more +commonly known as [description lists] `dl` in HTML) to any Markdown document. +Enable it via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - def_list +``` + +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 + [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] + +The [Footnotes] extension allows to define footnotes inline with the content, +which are then rendered after the content of the Markdown document. Enable it +via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - footnotes +``` + +No configuration options are supported. See reference for usage: + +- [Adding footnote references] +- [Adding footnote content] + + [Footnotes]: https://python-markdown.github.io/extensions/footnotes/ + [Footnotes added]: 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] + +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 +enabled via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - meta +``` + +No configuration options are available. See reference for usage: + +- [Setting the page title] +- [Setting the page description] +- [Hiding the sidebars] +- [Adding tags] + + [Metadata]: https://python-markdown.github.io/extensions/meta_data/ + [Metadata added]: 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 + [Adding tags]: ../../setup/setting-up-tags.md#adding-tags + +### Markdown in HTML + +[:octicons-workflow-24: Extension][Markdown in HTML] · +[:octicons-tag-24: 0.1.0 – present][Markdown in HTML added] + +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 +`mkdocs.yml`: + +``` yaml +markdown_extensions: + - md_in_html +``` + +> By default, Markdown ignores any content within a raw HTML block-level +> element. With the `md_in_html` extension enabled, the content of a raw HTML +> block-level element can be parsed as Markdown by including a markdown +> attribute on the opening tag. The markdown attribute will be stripped from +> the output, while all other attributes will be preserved. + +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 + [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] + +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. +Enable it via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - toc: + permalink: true +``` + +The following configuration options are supported: + +`permalink`{ #permalink } + +: :octicons-milestone-24: Default: `false` – This option adds an anchor link + containing the paragraph symbol `¶` or another custom symbol at the end of + each headline, exactly like on the page you're currently viewing, which + Material for MkDocs will make appear on hover: + + === "¶" + + ``` yaml + markdown_extensions: + - toc: + permalink: true + ``` + + === "⚓︎" + + ``` yaml + markdown_extensions: + - toc: + permalink: ⚓︎ + ``` + +`slugify`{ #slugify } + +: :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]: + + === "Unicode" + + ``` yaml + markdown_extensions: + - toc: + slugify: !!python/name:pymdownx.slugs.uslugify + ``` + + === "Unicode, case-sensitive" + + ``` yaml + markdown_extensions: + - toc: + slugify: !!python/name:pymdownx.slugs.uslugify_cased + ``` + +`toc_depth`{ #toc_depth } + +: :octicons-milestone-24: Default: `6` – Define the range of levels to be + included in the table of contents. This may be useful for project + documentation with deeply structured headings to decrease the length of the + table of contents, or to remove the table of contents altogether: + + === "Hide levels 4-6" + + ``` yaml + markdown_extensions: + - toc: + toc_depth: 3 + ``` + + === "Hide table of contents" + + ``` yaml + markdown_extensions: + - toc: + toc_depth: 0 + ``` + + [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 + [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] + +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 +enabled by default): + +``` yaml +markdown_extensions: + - tables +``` + +No configuration options are available. See reference for usage: + +- [Using data tables] +- [Column alignment] + + [Tables]: https://python-markdown.github.io/extensions/tables/ + [Tables added]: 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 + +## Superseded extensions + +The following [Python Markdown] extensions are not (or might not be) supported +anymore, and are therefore not recommended for use. Instead, the alternatives +should be considered. + +### Fenced Code Blocks + +[:octicons-workflow-24: Extension][Fenced Code Blocks] · +[:octicons-tag-24: 0.1.0 – present][Fenced Code Blocks added] + +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 + [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] + +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 + [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ + [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ diff --git a/mkdocs.yml b/mkdocs.yml index eb9711b94..22c82e3b8 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -196,6 +196,10 @@ nav: - Setting up the footer: setup/setting-up-the-footer.md - Adding a git repository: setup/adding-a-git-repository.md - Adding a comment system: setup/adding-a-comment-system.md + - Extensions: + - setup/extensions/index.md + - Python Markdown: setup/extensions/python-markdown.md + - Python Markdown Extensions: setup/extensions/python-markdown-extensions.md - Reference: - Abbreviations: reference/abbreviations.md - Admonitions: reference/admonitions.md From 3ac2bd2df0c23566d2009ddcc5f701c798960030 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 3 Oct 2021 09:11:15 +0200 Subject: [PATCH 02/18] Added documentation for Python Markdown Extensions --- docs/setup/extensions/index.md | 59 +++++++- .../extensions/python-markdown-extensions.md | 127 ++++++++++++++++++ docs/setup/extensions/python-markdown.md | 52 +++---- 3 files changed, 212 insertions(+), 26 deletions(-) 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/ From f1ee41ad6e387f36f38b699f9a7143c320643fbd Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 3 Oct 2021 11:32:20 +0200 Subject: [PATCH 03/18] Updated extension documentation --- .../extensions/python-markdown-extensions.md | 283 +++++++++++++++++- docs/setup/extensions/python-markdown.md | 11 +- 2 files changed, 273 insertions(+), 21 deletions(-) diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index dcea5232c..897da4142 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/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 -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. +The [Python Markdown Extensions] package is an excellent collection of +additional Markdown extensions that make technical writing a breeze. Material +for MkDocs lists this package as an explicit dependency, so it's automatically +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, -and integrates seamlessly with [MathJax][^1], a library for mathematical -typesetting. Enable it via `mkdocs.yml`: +The [Arithmatex] extension allows for rendering of block and inline block +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 @@ -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 -via `mkdocs.yml`: +added, deleted or updated sections in a Markdown document, e.g. for tracking +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 -resulting _call-outs_ collapsible, rendering +[:octicons-workflow-24: Extension][Details] · +[: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 diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index 92147f3c3..ad74b57d7 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/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/ From 4b433536c56c932ccd61626e49826c3614738c66 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 3 Oct 2021 13:33:01 +0200 Subject: [PATCH 04/18] Updated Python Markdown Extensions documentation --- docs/reference/lists.md | 2 +- docs/setup/extensions/index.md | 3 - .../extensions/python-markdown-extensions.md | 205 +++++++++++++++++- docs/setup/extensions/python-markdown.md | 32 +-- 4 files changed, 214 insertions(+), 28 deletions(-) diff --git a/docs/reference/lists.md b/docs/reference/lists.md index 3dfb52fa7..4944e2112 100644 --- a/docs/reference/lists.md +++ b/docs/reference/lists.md @@ -173,7 +173,7 @@ _Result_: [6]: #definition-list -### Using tasklists +### Using task lists When the [Tasklist][7] extension is enabled, unordered list items can be prefixed with `[ ]` to render an unchecked or `[x]` to render a checked diff --git a/docs/setup/extensions/index.md b/docs/setup/extensions/index.md index 50e46f811..5b5e5b288 100644 --- a/docs/setup/extensions/index.md +++ b/docs/setup/extensions/index.md @@ -56,8 +56,5 @@ title: Extensions # 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 897da4142..8b56f4793 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -14,7 +14,7 @@ installed with a supported version. ## 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 +_strongly recommended_. See the [overview][Extensions] page for a minimal and recommended configuration. [Extensions]: index.md @@ -73,8 +73,9 @@ of [additional JavaScript]: - 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. +The other configuration options of this extension are not officially supported +by Material for MkDocs, so they may yield unexpected results. Use them at your +own risk. See reference for usage: @@ -96,8 +97,8 @@ See reference for usage: [: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 Markdown document, e.g. for tracking -changes. Enable it via `mkdocs.yml`: +added, deleted or updated sections in a document, i.e. for tracking changes in +Markdown syntax. Enable it via `mkdocs.yml`: ``` yaml markdown_extensions: @@ -229,13 +230,17 @@ The following configuration options are supported: - overrides/.icons ``` +The other configuration options of this extension are not officially supported +by Material for MkDocs, so they may yield unexpected results. Use them at your +own risk. + See reference for usage: - [Using emojis] - [Using icons] - [Using icons in templates] - [Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/details/ + [Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/ [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 @@ -251,8 +256,7 @@ See reference for usage: 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`: +the help of [InlineHilite][InlineHilite #]). Enable it via `mkdocs.yml`: ``` yaml markdown_extensions: @@ -266,7 +270,7 @@ markdown_extensions: 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. + be necessary, but it's _strongly recommended_ anyway. The following configuration options are supported: @@ -349,6 +353,10 @@ The following configuration options are supported: copying a code block to the clipboard. Thus, the usage of either `table` or `pymdownx-inline` is recommended. +The other configuration options of this extension are not officially supported +by Material for MkDocs, so they may yield unexpected results. Use them at your +own risk. + See reference for usage: - [Specifying the language] @@ -398,14 +406,191 @@ No configuration options are supported. See reference for usage: [:octicons-workflow-24: Extension][Snippets] · [: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 +syntax. Enable it via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - pymdownx.snippets +``` + +The configuration options of this extension are not specific to Material for +MkDocs, as they only impact the Markdown parsing stage. See the [Snippets +documentation][Snippets] for more information. + +See reference for usage: + +- [Embedding external files] + + [Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ + [Snippets support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Embedding external files]: ../../reference/code-blocks.md#embedding-external-files + ### SuperFences -TODO: document Mermaid setup! +[:octicons-workflow-24: Extension][SuperFences] · +[: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 +blocks inside each other, including admonitions, tabs, lists and all other +elements. Enable it via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - pymdownx.superfences +``` + +The following configuration options are supported: + +`custom_fences`{ #custom_fences } + +: :octicons-milestone-24: Default: _none_ – This option allows to define a + handler for custom fences, e.g. to preserve the definitions of [Mermaid.js] + diagrams to be interpreted in the browser: + + ``` yaml + markdown_extensions: + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + ``` + + Note that this will primarily prevent syntax highlighting from being + applied. See the reference on [diagrams] to learn how Mermaid.js is + integrated with Material for MkDocs. + +The other configuration options of this extension are not officially supported +by Material for MkDocs, so they may yield unexpected results. Use them at your +own risk. + +See reference for usage: + +- [Using flowcharts] +- [Using sequence diagrams] +- [Using state diagrams] +- [Using class diagrams] +- [Using entity-relationship diagrams] + + [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ + [SuperFences support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Fenced Code Blocks]: python-markdown.md#fenced-code-blocks + [Mermaid.js]: https://mermaid-js.github.io/mermaid/ + [diagrams]: ../../reference/diagrams.md + [Using flowcharts]: ../../reference/diagrams.md#using-flowcharts + [Using sequence diagrams]: ../../reference/diagrams.md#using-sequence-diagrams + [Using state diagrams]: ../../reference/diagrams.md#using-state-diagrams + [Using class diagrams]: ../../reference/diagrams.md#using-class-diagrams + [Using entity-relationship diagrams]: ../../reference/diagrams.md#using-entity-relationship-diagrams ### Tabbed +[:octicons-workflow-24: Extension][Tabbed] · +[: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 +`mkdocs.yml`: + +``` yaml +markdown_extensions: + - pymdownx.tabbed: + alternate_style: true +``` + +The following configuration options are supported: + +`alternate_style`{ #alternate_style } + +: :octicons-milestone-24: Default: `false` · [:octicons-tag-24: 7.3.1] + [Tabbed alternate support] – This option enables the [alternate style] of + content tabs, which has [better behavior on smaller screen sizes], and thus + is _strongly recommended_: + + ``` yaml + markdown_extensions: + - pymdownx.tabbed: + alternate_style: true + ``` + +The other configuration options of this extension are not officially supported +by Material for MkDocs, so they may yield unexpected results. Use them at your +own risk. + +See reference for usage: + +- [Grouping code blocks] +- [Grouping other content] +- [Embedded content] + + [Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/ + [Tabbed support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0 + [Tabbed alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.1 + [alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style + [better behavior on smaller screen sizes]: https://twitter.com/squidfunk/status/1424740370596958214 + [Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks + [Grouping other content]: ../../reference/content-tabs.md#grouping-other-content + [Embedded content]: ../../reference/content-tabs.md#embedded-content + ### Tasklist +[:octicons-workflow-24: Extension][Tasklist] · +[: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 +it via `mkdocs.yml`: + +``` yaml +markdown_extensions: + - pymdownx.tasklist: + custom_checkbox: true +``` + +The following configuration options are supported: + +`custom_checkbox`{ #custom-checkbox } + +: :octicons-milestone-24: Default: `false` · This option toggles the rendering + style of checkboxes, replacing native checkbox styles with beautiful icons, + and is therefore _strongly recommended_: + + ``` yaml + markdown_extensions: + - pymdownx.tasklist: + custom_checkbox: true + ``` + +`clickable_checkbox`{ #clickable-checkbox } + +: :octicons-milestone-24: Default: `false` · This option toggles whether + checkboxes are clickable. As the state is not persisted, the use of this + option is _rather discouraged_ from a user experience perspective: + + ``` yaml + markdown_extensions: + - pymdownx.tasklist: + clickable_checkbox: true + ``` + +The other configuration options of this extension are not officially supported +by Material for MkDocs, so they may yield unexpected results. Use them at your +own risk. + +See reference for usage: + +- [Using task lists] + + [Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/ + [Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 + [GitHub Flavored Markdown]: https://github.github.com/gfm/ + [Tasklist #]: #tasklist + [Spec]: https://github.github.com/gfm/#task-list-items-extension- + [Using task lists]: ../../reference/lists.md#using-task-lists + ### Other - Caret diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index ad74b57d7..88a2e9c05 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -14,7 +14,7 @@ reference for what features they need to be enabled. ## 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 +_strongly recommended_. See the [overview][Extensions] page for a minimal and recommended configuration. [Extensions]: index.md @@ -49,8 +49,8 @@ No configuration options are available. See reference for usage: [: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 -via `mkdocs.yml`: +_call-outs_, which can be defined in Markdown by using a simple syntax. Enable +it via `mkdocs.yml`: ``` yaml markdown_extensions: @@ -106,8 +106,8 @@ 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. -Enable it via `mkdocs.yml`: +commonly known as [description lists] – `dl` in HTML) via Markdown to a +document. Enable it via `mkdocs.yml`: ``` yaml markdown_extensions: @@ -129,7 +129,7 @@ No configuration options are available. See reference for usage: [: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 +which are then rendered after the Markdown content of a document. Enable it via `mkdocs.yml`: ``` yaml @@ -153,8 +153,8 @@ No configuration options are supported. See reference for usage: [: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 -enabled via `mkdocs.yml`: +to a document via front matter written in YAML syntax before the Markdown. It +can be enabled via `mkdocs.yml`: ``` yaml markdown_extensions: @@ -208,9 +208,9 @@ No configuration options are available. See reference for usage: [:octicons-workflow-24: Extension][Table of Contents] · [: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. -Enable it via `mkdocs.yml`: +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 +page. Enable it via `mkdocs.yml`: ``` yaml markdown_extensions: @@ -289,6 +289,10 @@ The following configuration options are supported: toc_depth: 0 ``` +The other configuration options of this extension are not officially supported +by Material for MkDocs, so they may yield unexpected results. Use them at your +own risk. + [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/ @@ -298,9 +302,9 @@ The following configuration options are supported: [:octicons-workflow-24: Extension][Tables] · [: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 -enabled by default): +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 +default): ``` yaml markdown_extensions: From 8e527be8b254375f139fa2a76531e536c3448546 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 3 Oct 2021 14:54:22 +0200 Subject: [PATCH 05/18] Updated Extension documentation --- docs/setup/extensions/index.md | 173 +++++++++++++----- .../extensions/python-markdown-extensions.md | 135 +++++++++++--- docs/setup/extensions/python-markdown.md | 24 +-- 3 files changed, 253 insertions(+), 79 deletions(-) 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 From b8becde3bb5bffbd9f3b19b79b9b5e5b7205b5a2 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 3 Oct 2021 15:32:50 +0200 Subject: [PATCH 06/18] Updated Admonition documentation --- docs/reference/admonitions.md | 190 ++++++------------ .../extensions/python-markdown-extensions.md | 2 +- 2 files changed, 58 insertions(+), 134 deletions(-) diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md index 239cc43cd..a1895f4d0 100644 --- a/docs/reference/admonitions.md +++ b/docs/reference/admonitions.md @@ -11,61 +11,38 @@ inclusion and nesting of arbitrary content. ## Configuration -### Admonition - -[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2] - -The [Admonition][2] extension, which is part of the standard Markdown -library, is integrated with Material for MkDocs and can be enabled via -`mkdocs.yml`: +The following configuration enables admonitions, allows to make them collapsible +and to nest arbitrary content inside admonition bodies. Add the following lines +to `mkdocs.yml`: ``` yaml markdown_extensions: - admonition -``` - - [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss - [2]: https://python-markdown.github.io/extensions/admonition/ - -### Details - -[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4] - -The [Details][4] extension, which is part of [Python Markdown Extensions][5], -adds the ability to __make admonitions collapsible__. It can be enabled via -`mkdocs.yml`: - -``` yaml -markdown_extensions: - pymdownx.details -``` - - [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_details.scss - [4]: https://facelessuser.github.io/pymdown-extensions/extensions/details/ - [5]: https://facelessuser.github.io/pymdown-extensions/ - -### SuperFences - -The [SuperFences][6] extension, which is also part of [Python Markdown -Extensions][5], allows for the __nesting of code and content blocks inside -admonitions__, and is therefore strongly recommended: - -``` yaml -markdown_extensions: - pymdownx.superfences ``` - [6]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ + +See additional configuration options: + +- [Admonition] +- [Details] +- [SuperFences] + + [Admonition]: ../setup/extensions/python-markdown.md#admonition + [Details]: ../setup/extensions/python-markdown-extensions.md#details + [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences ## Usage -Admonitions follow a simple syntax: a block must start with `!!!`, followed -by a single keyword which is used as the [type qualifier][7] of the block. The -content of the block then follows on the next line, indented by four spaces. +Admonitions follow a simple syntax: a block starts with `!!!`, followed by a +single keyword used as a [type qualifier]. The content of the block follows on +the next line, indented by four spaces. _Example_: ``` markdown !!! note + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -79,7 +56,7 @@ _Result_: nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. - [7]: #supported-types + [type qualifier]: #supported-types ### Changing the title @@ -91,6 +68,7 @@ _Example_: ``` markdown !!! note "Phasellus posuere in sem ut cursus" + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -106,14 +84,15 @@ _Result_: ### Removing the title -Similar to [changing the title][8], the icon and title can be omitted entirely -by adding an empty string directly after the type qualifier. Note that this -will not work for [collapsible blocks][9]. +Similar to [changing the title], the icon and title can be omitted entirely by +adding an empty string directly after the type qualifier. Note that this will +not work for [collapsible blocks]. _Example_: ``` markdown !!! note "" + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -127,70 +106,20 @@ _Result_: nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. - [8]: #changing-the-title - [9]: #collapsible-blocks - -### Embedded content - -Admonitions can contain all kinds of text content, including headlines, lists, -paragraphs and other blocks. While the parser from the standard Markdown library -doesn't account for nested blocks, the [SuperFences][10] extension adds the -ability to nest arbitrary content inside admonitions. - -_Example_: - -``` markdown -!!! note - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - - ``` python - def bubble_sort(items): - for i in range(len(items)): - for j in range(len(items) - 1 - i): - if items[j] > items[j + 1]: - items[j], items[j + 1] = items[j + 1], items[j] - ``` - - Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in - sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis. - Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim. -``` - -_Result_: - -!!! note - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - - ``` python - def bubble_sort(items): - for i in range(len(items)): - for j in range(len(items) - 1 - i): - if items[j] > items[j + 1]: - items[j], items[j + 1] = items[j + 1], items[j] - ``` - - Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in - sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis. - Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim. - - [10]: #superfences + [changing the title]: #changing-the-title + [collapsible blocks]: #collapsible-blocks ### Collapsible blocks -The [Details][11] extension adds support for rendering collapsible admonition -blocks. This is useful for FAQs or content that is of secondary nature. A -details block follows the syntax and semantics of admonition blocks, but must -start with `???`. +If the [Details] extension is enabled and an admonition is started with `???` +instead of `!!!`, the admonition is rendered as a collapsible block with a +small marker on the right side. _Example_: ``` markdown ??? note + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -204,12 +133,13 @@ _Result_: nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -Adding a `+` after `???` will render the block as open on page load: +Adding a `+` after the `???` token will render the block as open. _Example_: ``` markdown ???+ note + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -223,23 +153,13 @@ _Result_: nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. - [11]: #details - ### Inline blocks -[:octicons-file-code-24: Source][12] · -:octicons-beaker-24: Experimental +Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing +them to the right using the `inline` + `end` modifiers, or to the left using +only the `inline` modifier. -Admonitions and [Details][11] can also be rendered as inline blocks (i.e. -sidebars), placing them to the right using the `inline` + `end` modifiers, or -to the left using only the `inline` modifier. - -__Important__: Admonitions that use the `inline` modifiers _must_ be declared -prior to the content block you want to place them beside. If there's -insufficient space to render the admonition next to the block, the admonition -will stretch to the full width of the viewport, e.g. on mobile viewports. - -=== "inline end" +=== ":octicons-arrow-right-16: inline end" _Example_ / _Result_: @@ -251,6 +171,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. ``` markdown !!! info inline end + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat @@ -260,7 +181,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. Use `inline end` to align to the right (left for rtl languages). -=== "inline" +=== ":octicons-arrow-left-16: inline" _Example_ / _Result_: @@ -272,6 +193,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. ``` markdown !!! info inline + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat @@ -281,7 +203,10 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. Use `inline` to align to the left (right for rtl languages). - [12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_modifiers.scss +__Important__: Admonitions that use the `inline` modifiers _must_ be declared +prior to the content block you want to place them beside. If there's +insufficient space to render the admonition next to the block, the admonition +will stretch to the full width of the viewport, e.g. on mobile viewports. ### Supported types @@ -389,18 +314,17 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: in order to make it easier for authors to migrate to Material for MkDocs. However, when the title is omitted, the admonition extension will render it as `Seealso`, which is incorrect English. For this reason, it was deprecated - as of 7.1.5 and will be removed in 8.x. + in :octicons-tag-24: 7.1.5 and will be removed in :octicons-tag-24: 8.0.0. ### Changing the icons -[:octicons-file-code-24: Source][13] · -[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][13]{ .mdx-insiders } +> This feature is currently only available in [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } Each of the supported admonition types has a distinct icon, which can be changed to any icon bundled with the theme. Just set the name of the admonition type to a valid icon in `mkdocs.yml`: -=== "Octicons" +=== ":octicons-mark-github-16: Octicons" _Example_: @@ -424,10 +348,10 @@ a valid icon in `mkdocs.yml`: _Result_: - [![Admonition with Octicons icons][14]][14] + [![Admonition with Octicons icons][Octicons]][Octicons] -=== "FontAwesome" +=== ":fontawesome-brands-font-awesome: FontAwesome" _Example_: @@ -451,19 +375,19 @@ a valid icon in `mkdocs.yml`: _Result_: - [![Admonition with FontAwesome icons][15]][15] + [![Admonition with FontAwesome icons][FontAwesome]][FontAwesome] - [13]: ../insiders/index.md - [14]: ../assets/screenshots/admonition-octicons.png - [15]: ../assets/screenshots/admonition-fontawesome.png + [Insiders]: ../insiders/index.md + [Octicons]: ../assets/screenshots/admonition-octicons.png + [FontAwesome]: ../assets/screenshots/admonition-fontawesome.png ## Customization ### Custom admonitions If you want to add a custom admonition type, all you need is a color and an -`svg` icon. Copy the icon's `svg` code from the [`.icons`][16] folder and add the -following CSS to an [additional stylesheet][17]: +`*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder +and add the following CSS to an [additional stylesheet]: ``` css :root { @@ -488,7 +412,7 @@ following CSS to an [additional stylesheet][17]: You should now be able to create an admonition of the `pied-piper` type. Note that you can also use this technique to override existing admonition icons or -colors. [You can even add animations][18]. +colors. [You can even add animations][Custom animations].