Material 5.0.0 Beta 1

This thread is meant for feedback on the first beta release of Material 5.0. Please post any issues or errors encountered during setup and/or migration.

The first beta focuses on the rewrite of the underlying JavaScript code to a new, more modern architecture based on TypeScript and RxJS. However, it also provides some new features.

The probably biggest feature is the new search functionality which was completely rewritten and is now running inside a web worker. Furthermore, it supports prebuilt indexes (albeit this is not recommended). Previously, the search index was built when the search was focussed for the first time. Sometimes this led to lags and the UI freezing, as the search index needed to be constructed. The construction is now done upon page load inside a web worker.

Additionally, most of lunr’s query syntax is now supported, e.g.:

color -primary +accent

Fixed issues

• Add ‘selected’ as toc item state (#1102)
• Update Font Awesome to LATEST (#756)
• Fix rendering issues in table of contents (#1292)
• Add announcement bar (#1190)
• Add missing background-color definition on root (#1418)
• Fix error on clipboard in combination with superfences (#1440)

Installation

Install the beta via pip:

pip install mkdocs-material>=5.0.0b1

Migration

Material 5.0 is mostly downward compatible but includes some breaking changes. Following is a list of changes that need to be made to your mkdocs.yml. Note that you only need to adjust the values if you defined them.

Search

Search is now configured as part of the search plugin configuration.

Material 4.x:

extra:
  search:
    language: 'en, de, ru'
    tokenizer: '[\s\-\.]+'

Material 5.x:

plugins:
  - search:
      separator: '[\s\-\.]+'
      lang:
        - en
        - de
        - ru

Social links

Font Awesome was updated to the latest version and is now provided via inline SVGs which reduces the overall footprint. To reference an icon, reference its path from the top-level .fontawesome directory which is distributed with the theme without the .svg at the end.

Material 4.x:

extra:
  social:
    - type: 'github'
      link: 'https://github.com/squidfunk'
    - type: 'twitter'
      link: 'https://twitter.com/squidfunk'
    - type: 'linkedin'
      link: 'https://www.linkedin.com/in/squidfunk'

Material 5.x:

extra:
  social:
    - icon: brands/github-alt
      link: https://github.com/squidfunk
    - icon: brands/twitter
      link: https://twitter.com/squidfunk
    - icon: brands/linkedin
      link: https://www.linkedin.com/in/squidfunk/

Note that mkdocs build will now terminate with an error if an invalid icon is referenced.

Templates

Note that some of the templates changed. If you extended the theme by overriding blocks or partials, you might have to adjust the HTML of your overrides. We’re working on a list of changes, but for now you can use the diff functionality of GitHub.

[Nelyah]

Awesome! Thank you for your work 😄 Super excited to see this come live!

[wilhelmer]

Furthermore this so called instant loading feature will be optional and experimental. It will at all times be opt-in.

Ahh that’s good to know, thank you.

Burying the packing approach is no problem for me, good riddance 👋