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

Updated Extension documentation

Browse Source
This commit is contained in:
squidfunk 2021-10-03 14:54:22 +02:00
parent 4b433536c5
commit 8e527be8b2
3 changed files with 253 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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"
<div class="mdx-columns" markdown="1">
``` 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
</div>
# 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
```

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

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

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

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