mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-09-24 19:38:27 +02:00
Updated extension documentation
This commit is contained in:
squidfunk
parent
4fab8a4471
commit
f1ee41ad6e
@ -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
|
||||
|
||||
@ -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/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user