Material 5.0.0 Beta 2

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

The second beta includes several bugfixes and also adds some new features.

Instant loading

Theory of operation

The basic idea is: why should we reconstruct the whole page again and again when only the content and navigation changes? When instant loading is enabled, all internal links are intercepted and dispatched via XHR. The resulting document is parsed, injected and all event handlers are automatically rebound. The search index will remain intact in-between loads.

With instant loading enabled, Material effectively behaves like a Single Page Application.

This feature shows the true beauty of the new architecture - everything is observable and automatically updates when new values become available. However, instant loading is experimental. It will definitely be part of the next major version, but will remain in an experimental state until we fleshed out the biggest bugs. It will at all times remain opt-in, thus it has to be enabled explicitly:

theme:
  feature:
    instant: true

Demo

The following gifs were recorded on Fast 3G to show the speed advantage of instant loading:

Without instant loading

With instant loading

Known bugs

• When a link from the search is clicked, the browser doesn’t jump to the right place
• Google Analytics is not triggered again
• Search doesn’t work when use_directory_urls is set to false
• Scroll snap on 2nd+ tab for screen navigation doesn’t correctly lock into place

All fixed in HEAD of refactor/rxjs-typescript

Changelog

Bugfixes

• Fixed multi-language search not being correctly initialized
• Fixed invalid anchor list offset for hidden anchors
• Fixed failing anchor jump for anchors inside closed details
• Lots and lots of other small improvements

Features

• Added new experimental theme.feature.instant configuration option
• Added p / , (previous page) and n / . (next page) hotkeys
• Added support for variable sized header – sidebars now lock correctly into place
• Added a generic snackbar implementation, currently only used by copy-to-clipboard
• Added GitLab support (stars + forks retrieval)

Installation

pip install mkdocs-material>=5.0.0b2

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.

Feedback is appreciated!

[squidfunk]

@Nelyah hmm that’s difficult to say. I’ll try to reproduce your problem but it could also be already resolved on the tip of the branch. Would wait until the next pre-release.

[facelessuser]

@ofek, are you using the unreleased tip of the branch instead of beta2? Icons got moved around again and will probably be different for beta3. They were changed so that you can use Material or Fontawesome.