Skip to content


This page includes a list of deprecations, indicating which features of Material for MkDocs were replaced with newer, more flexible alternatives, and thus should not be used anymore.

Front matter


Deprecated: 5.5.0 · Removal: 6.x

The redirect key, which could be added via Metadata, allowed to specify a redirect from within a document to a new address, which is a good idea when moving content around:

redirect: /path/to/new/file

The redirects plugin provides the ability to define redirect mappings via mkdocs.yml, which is considered to be a much better solution to achieve the same result. It can be installed with pip:

pip install mkdocs-redirects

Redirect mappings can then be added to mkdocs.yml:

  - redirects:
        path/to/old/ path/to/new/

Deprecated: 5.5.0 · Removal: 6.x

The source and path keys, which could be added via Metadata, showed a source icon at the top right corner of a document, linking a document to a single source file:

path: tree/master/docs

Only a single source file could be linked, which is useless if a document refers to multiple files (or multiple sections within a single file). A more flexible approach is to use the new icon integration:

[:octicons-file-code-24: Source](

This will render as Source, which can be included at arbitrary positions in any document.


Deprecated: 5.5.0 · Removal: 6.x

The hero key, which could be added via Metadata, allowed to render a simple, text-only and page-local teaser text as part of a document. It could be set from front matter with:

hero: Lorem ipsum dolor sit amet

The recommended way is to override the hero block via theme extension for a specific page, which has the nice side effect that hero templates can be shared among multiple pages:

template: overrides/hero.html
{% block hero %}
  <!-- Add custom hero here -->
{% endblock %}