mkdocs-material/docs/setup/extensions/python-markdown.md

template
overrides/main.html

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 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 page for a minimal and recommended configuration.

Abbreviations

:octicons-workflow-24: Extension · :octicons-tag-24: 1.0.0 – present

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 supported. Enable it via mkdocs.yml:

markdown_extensions:
  - abbr

No configuration options are available. See reference for usage:

• Adding abbreviations

• Adding a glossary

Admonition

:octicons-workflow-24: Extension · :octicons-tag-24: 0.1.0 – present

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:

markdown_extensions:
  - admonition

No configuration options are available. See reference for usage:

• Adding admonitions

• Changing the title

• Removing the title

• Supported types

Attribute Lists

:octicons-workflow-24: Extension · :octicons-tag-24: 0.1.0 – present

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:

• Adding buttons

• Adding icons with colors

• Image alignment

• Image lazy-loading

Definition Lists

:octicons-workflow-24: Extension · :octicons-tag-24: 1.1.0 – present

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:

markdown_extensions:
  - def_list

No configuration options are available. See reference for usage:

• Using definition lists

Footnotes

:octicons-workflow-24: Extension · :octicons-tag-24: 1.0.0 – present

The Footnotes extension allows to define footnotes inline with the content, which are then rendered after the content of the Markdown document. Enable it via mkdocs.yml:

markdown_extensions:
  - footnotes

No configuration options are supported. See reference for usage:

• Adding footnote references

• Adding footnote content

Metadata

:octicons-workflow-24: Extension · :octicons-tag-24: 1.0.0 – present

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:

markdown_extensions:
  - meta

No configuration options are available. See reference for usage:

• Setting the page title

• Setting the page description

• Hiding the sidebars

• Adding tags

Markdown in HTML

:octicons-workflow-24: Extension · :octicons-tag-24: 0.1.0 – present

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 mkdocs.yml:

markdown_extensions:
  - md_in_html

By default, Markdown ignores any content within a raw HTML block-level element. With the md_in_html extension enabled, the content of a raw HTML block-level element can be parsed as Markdown by including a markdown attribute on the opening tag. The markdown attribute will be stripped from the output, while all other attributes will be preserved.

No configuration options are available. See reference for usage:

• Image captions

Table of Contents

:octicons-workflow-24: Extension · :octicons-tag-24: 0.1.0 – present

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:

markdown_extensions:
  - toc:
      permalink: true

The following configuration options are supported:

permalink{ #permalink }

:octicons-milestone-24: Default: false – 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: ⚓︎
```

slugify{ #slugify }

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

=== "Unicode"

``` yaml
markdown_extensions:
  - toc:
      slugify: !!python/name:pymdownx.slugs.uslugify
```

=== "Unicode, case-sensitive"

``` yaml
markdown_extensions:
  - toc:
      slugify: !!python/name:pymdownx.slugs.uslugify_cased
```

toc_depth{ #toc_depth }

:octicons-milestone-24: Default: 6 – 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
```

Tables

:octicons-workflow-24: Extension · :octicons-tag-24: 0.1.0 – present

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

markdown_extensions:
  - tables

No configuration options are available. See reference for usage:

• Using data tables

• Column alignment

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

:octicons-workflow-24: Extension · :octicons-tag-24: 0.1.0 – present

Superseded by SuperFences. This extension might still work, but the SuperFences extension is superior in many ways, as it allows for arbitrary nesting, and therefore strongly recommended.

CodeHilite

:octicons-workflow-24: Extension · :octicons-tag-24: 0.1.0 – 5.5.14

Superseded by Highlight. Support for CodeHilite was dropped in version 6.0.0, as Highlight has a better integration with other essential extensions like SuperFences and InlineHilite.