mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-28 01:10:58 +01:00
Updated Python Markdown Extensions documentation
This commit is contained in:
squidfunk
parent
139a02f552
commit
4b433536c5
@ -56,8 +56,5 @@ title: Extensions
|
||||
|
||||
# Python Markdown Extensions
|
||||
- pymdownx.highlight
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
```
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user