7d6d8d7a7c
Unicode, case-sensitive reference setting causes error below.
```
yaml.constructor.ConstructorError: expected a mapping node, but found scalar
```
Update related sections in the documentation to address this issue.
Newer Python-Markdown has `slugify_unicode` built-in, so this
```yaml
markdown_extensions:
- toc:
slugify: !!python/name:markdown.extensions.toc.slugify_unicode
```
also works for case-insensitive use cases.
Fixes: ee1e675da6 ("Update slug reference")
11 KiB
Python Markdown
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 which features they need to be enabled.
Supported extensions
Abbreviations
The Abbreviations extension adds the ability to add a small tooltip to an
element, by wrapping it with an abbr tag. Only plain text (no markup) is
supported. Enable it via mkdocs.yml:
markdown_extensions:
- abbr
No configuration options are available. See reference for usage:
Admonition
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
it via mkdocs.yml:
markdown_extensions:
- admonition
No configuration options are available. See reference for usage:
Attribute Lists
The Attribute Lists extension allows to add HTML attributes and CSS classes
to almost every Markdown inline- and block-level
element with a special syntax. Enable it via mkdocs.yml:
markdown_extensions:
- attr_list
No configuration options are available. See reference for usage:
Definition Lists
The Definition Lists extension adds the ability to add definition lists (more
commonly known as description lists – dl in HTML) via Markdown to a
document. Enable it via mkdocs.yml:
markdown_extensions:
- def_list
No configuration options are available. See reference for usage:
Footnotes
The Footnotes extension allows to define inline footnotes, which are then
rendered below all Markdown content of a document. Enable it via mkdocs.yml:
markdown_extensions:
- footnotes
No configuration options are supported. See reference for usage:
Markdown in HTML
The Markdown in HTML extension allows for writing Markdown inside of HTML,
which is useful for wrapping Markdown content with custom elements. Enable it
via mkdocs.yml:
markdown_extensions:
- md_in_html
By default, Markdown ignores any content within a raw HTML block-level element. With the
md_in_htmlextension enabled, the content of a raw HTML block-level element can be parsed as Markdown by including amarkdownattribute on the opening tag. Themarkdownattribute will be stripped from the output, while all other attributes will be preserved.
No configuration options are available. See reference for usage:
Table of Contents
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:
markdown_extensions:
- toc:
permalink: true
The following configuration options are supported:
: –
This option sets the title of the table of contents in the right navigation
sidebar, which is normally automatically sourced from the translations for
the site language as set in mkdocs.yml:
``` yaml
markdown_extensions:
- toc:
title: On this page
```
: This option adds an anchor link
containing the paragraph symbol ¶ or another custom symbol at the end of
each headline, exactly like on the page you're currently viewing, which
Material for MkDocs will make appear on hover:
=== "¶"
``` yaml
markdown_extensions:
- toc:
permalink: true
```
=== "⚓︎"
``` yaml
markdown_extensions:
- toc:
permalink: ⚓︎
```
: This option sets the title of the anchor link which is shown on hover and read by screen readers. For accessibility reasons, it might be beneficial to change it to a more discernable name, stating that the anchor links to the section itself:
``` yaml
markdown_extensions:
- toc:
permalink_title: Anchor link to this section for reference
```
: 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:
=== "Unicode"
``` yaml
markdown_extensions:
- toc:
slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
=== "Unicode, case-sensitive"
``` yaml
markdown_extensions:
- toc:
slugify: !!python/object/apply:pymdownx.slugs.slugify {}
```
: Define the range of levels to be included in the table of contents. This may be useful for project documentation with deeply structured headings to decrease the length of the table of contents, or to remove the table of contents altogether:
=== "Hide levels 4-6"
``` yaml
markdown_extensions:
- toc:
toc_depth: 3
```
=== "Hide table of contents"
``` yaml
markdown_extensions:
- toc:
toc_depth: 0
```
The other configuration options of this extension are not officially supported by Material for MkDocs, which is why they may yield unexpected results. Use them at your own risk.
Tables
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):
markdown_extensions:
- tables
No configuration options are available. See reference for usage:
Superseded extensions
The following Python Markdown extensions are not (or might not be) supported anymore, and are therefore not recommended for use. Instead, the alternatives should be considered.
Fenced Code Blocks
Superseded by SuperFences. This extension might still work, but the SuperFences extension is superior in many ways, as it allows for arbitrary nesting, and is therefore recommended.
CodeHilite
Superseded by Highlight. Support for CodeHilite was dropped in
, as [Highlight] has a better integration with otheressential extensions like SuperFences and InlineHilite.