OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Added documentation for Python Markdown Extensions

Browse Source
This commit is contained in:
squidfunk 2021-10-03 09:11:15 +02:00
parent 30943cc629
commit 3ac2bd2df0
3 changed files with 212 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
docs/setup/extensions/index.md
View File

@ -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
```

127
docs/setup/extensions/python-markdown-extensions.md
View File

@ -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

52
docs/setup/extensions/python-markdown.md
View File

@ -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/