Skip to content

Deprecations

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

Redirect

Deprecated: 5.5 · Removed: 6.0

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:

plugins:
  - redirects:
      redirect_maps:
        path/to/old/file.md: path/to/new/file.md

Deprecated: 5.5 · Removed: 6.0

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
source: deprecations.md
---

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](https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md)

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

Hero

Deprecated: 5.5 · Removed: 6.0

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 %}

Docker image

Bundled plugins

Deprecated: 5.5 · Removed: 6.0

Over the last years, the Docker image has continually increased in size. For CI it's important that download times are as short as possible, which is why the following plugins will be removed:

Note that it's trivial to install plugins inside the Docker image before building your documentation. See the installation guide for a step-by-step guide.