How to upgrade

How to upgrade

Upgrade to the latest version with:

pip install --upgrade --force-reinstall mkdocs-material

Show the currently installed version with:

pip show mkdocs-material

Upgrading from 8.x to 9.x

This major release includes a brand new search implementation that is faster and allows for rich previews, advanced tokenization and better highlighting. It was available as part of Insiders for over a year, and now that the funding goal was hit, makes its way into the community edition.

Changes to mkdocs.yml

content.code.copy

The copy-to-clipboard buttons are now opt-in and can be enabled or disabled per block. If you wish to enable them for all code blocks, add the following lines to mkdocs.yml:

yaml 
theme:
  features:
    - content.code.copy

content.action.*

A “view source” button can be shown next to the “edit this page” button, both of which must now be explicitly enabled. Add the following lines to mkdocs.yml:

yaml 
theme:
  features:
    - content.action.edit
    - content.action.view

The previous and next buttons in the footer are now opt-in. If you wish to keep them for your documentation, add the following lines to mkdocs.yml:

yaml 
theme:
  features:
    - navigation.footer

theme.language

The Korean and Norwegian language codes were renamed, as they were non-standard:

  • kr to ko

  • no to nb

feedback.ratings

The old, nameless placeholders were removed (after being deprecated for several months). Make sure to switch to the new named placeholders {title} and {url}:

https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}

Changes to *.html files

The templates have undergone a series of changes. If you have customized Material for MkDocs with theme extension, be sure to incorporate the latest changes into your templates. A good starting point is to inspect the diff.

Built-in plugins not working after upgrade?

If one of the built-in plugins (search or tags) doesn’t work anymore without any apparent error or cause, it is very likely related to custom overrides. MkDocs 1.4.1 and above allow themes to namespace built-in plugins, which Material for MkDocs 9 now does in order to allow authors to use third-party plugins with the same name as built-in plugins. Search your overrides for "in config.plugins" and add the material/ namespace. Affected partials:

Upgrading from 7.x to 8.x

What’s new?

  • Added support for code annotations

  • Added support for anchor tracking

  • Added support for version warning

  • Added copyright partial for easier override

  • Removed deprecated content tabs legacy implementation

  • Removed deprecated seealso admonition type

  • Removed deprecated site_keywords setting (unsupported by MkDocs)

  • Removed deprecated prebuilt search index support

  • Removed deprecated web app manifest – use customization

  • Removed extracopyright variable – use new copyright partial

  • Removed Disqus integration – use customization

  • Switched to :is() selectors for simple selector lists

  • Switched autoprefixer from last 4 years to last 2 years

  • Improved CSS overall to match modern standards

  • Improved CSS variable semantics for fonts

  • Improved extensibility by restructuring partials

  • Improved handling of details when printing

  • Improved keyboard navigation for footnotes

  • Fixed #3214: Search highlighting breaks site when empty

Changes to mkdocs.yml

pymdownx.tabbed

Support for the legacy style of the Tabbed extension was dropped in favor of the new, alternate implementation which has better behavior on mobile viewports:

pymdownx.superfences

The *-experimental suffix must be removed from the custom fence class property, which is used to target code blocks to be rendered as diagrams using Mermaid.js:

google_analytics

This option was deprecated in MkDocs 1.2.0, as the implementation of a JavaScript-based analytics integration is the responsibility of a theme. The following lines must be changed:

Changes to *.html files

The templates have undergone a set of changes to make them future-proof. If you’ve used theme extension to override a block or template, make sure that it matches the new structure:

  • If you’ve overridden a block, check base.html for potential changes

  • If you’ve overridden a template, check the respective *.html file for potential changes

Upgrading from 6.x to 7.x

What’s new?

  • Added support for deploying multiple versions

  • Added support for integrating a language selector

  • Added support for rendering admonitions as inline blocks

  • Rewrite of the underlying reactive architecture

  • Removed Webpack in favor of reactive build strategy (–480 dependencies)

  • Fixed keyboard navigation for code blocks after content tabs switch

Changes to mkdocs.yml

extra.version.method

The versioning method configuration was renamed to extra.version.provider to allow for different versioning strategies in the future:

Changes to *.html files

The templates have undergone a set of changes to make them future-proof. If you’ve used theme extension to override a block or template, make sure that it matches the new structure:

  • If you’ve overridden a block, check base.html for potential changes

  • If you’ve overridden a template, check the respective *.html file for potential changes

Upgrading from 5.x to 6.x

What’s new?

  • Improved search result look and feel

  • Improved search result stability while typing

  • Improved search result grouping (pages + headings)

  • Improved search result relevance and scoring

  • Added display of missing query terms to search results

  • Reduced size of vendor bundle by 25% (84kb → 67kb)

  • Reduced size of the Docker image to improve CI build performance

  • Removed hero partial in favor of custom implementation

  • Removed deprecated front matter features

Changes to mkdocs.yml

Following is a list of changes that need to be made to mkdocs.yml. Note that you only have to adjust the value if you defined it, so if your configuration does not contain the key, you can skip it.

theme.features

All feature flags that can be set from mkdocs.yml, like tabs and instant loading, are now prefixed with the name of the component or function they apply to, e.g. navigation.*:

Changes to *.html files

The templates have undergone a set of changes to make them future-proof. If you’ve used theme extension to override a block or template, make sure that it matches the new structure:

  • If you’ve overridden a block, check base.html for potential changes

  • If you’ve overridden a template, check the respective *.html file for potential changes

Upgrading from 4.x to 5.x

What’s new?

  • Reactive architecture – try #!js app.dialog$.next("Hi!") in the console

  • Instant loading – make Material behave like a Single Page Application

  • Improved CSS customization with CSS variables – set your brand’s colors

  • Improved CSS resilience, e.g. proper sidebar locking for customized headers

  • Improved icon integration and configuration – now including over 5k icons

  • Added possibility to use any icon for logo, repository and social links

  • Search UI does not freeze anymore (moved to web worker)

  • Search index built only once when using instant loading

  • Improved extensible keyboard handling

  • Support for prebuilt search indexes

  • Support for displaying stars and forks for GitLab repositories

  • Support for scroll snapping of sidebars and search results

  • Reduced HTML and CSS footprint due to deprecation of Internet Explorer support

  • Slight facelifting of some UI elements (admonitions, tables, …)

Changes to mkdocs.yml

Following is a list of changes that need to be made to mkdocs.yml. Note that you only have to adjust the value if you defined it, so if your configuration does not contain the key, you can skip it.

theme.feature

Optional features like tabs and instant loading are now implemented as flags and can be enabled by listing them in mkdocs.yml under theme.features:

theme.logo.icon

The logo icon configuration was centralized under theme.icon.logo and can now be set to any of the icons bundled with the theme:

extra.repo_icon

The repo icon configuration was centralized under theme.icon.repo and can now be set to any of the icons bundled with the theme:

extra.search.*

Search is now configured as part of the plugin options. Note that the search languages must now be listed as an array of strings and the tokenizer was renamed to separator:

extra.social.*

Social links stayed in the same place, but the type key was renamed to icon in order to match the new way of specifying which icon to be used:

Changes to *.html files

The templates have undergone a set of changes to make them future-proof. If you’ve used theme extension to override a block or template, make sure that it matches the new structure:

  • If you’ve overridden a block, check base.html for potential changes

  • If you’ve overridden a template, check the respective *.html file for potential changes

Upgrading from 3.x to 4.x

What’s new?

Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix includes a mandatory change of the base font-size from 10px to 20px which means all rem values needed to be updated. Within the theme, px to rem calculation is now encapsulated in a new function called px2rem which is part of the SASS code base.

If you use Material for MkDocs with custom CSS that is based on rem values, note that those values must now be divided by 2. Now, 1.0rem doesn’t map to 10px, but 20px. To learn more about the problem and implications, please refer to #911 in which the problem was discovered and fixed.

Changes to mkdocs.yml

None.

Changes to *.html files

None.