Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-24 07:30:12 +01:00
Code Issues Releases Wiki Activity

Updated Python Markdown Extensions documentation

Browse Source
This commit is contained in:
squidfunk 2021-10-03 13:33:01 +02:00
parent 139a02f552
commit 4b433536c5
4 changed files with 214 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/lists.md
View File

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

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

@ -56,8 +56,5 @@ title: Extensions
# Python Markdown Extensions
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
```

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

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

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

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