Material 5.0.0 Beta 1

[squidfunk]

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 (Add 'selected' as toc item state #1102)
• Update Font Awesome to LATEST (Update Font Awesome to 5.0 – breaking change #756)
• Fix rendering issues in table of contents (Table of Contents is blurry #1292)
• Add announcement bar (Feature request: add an annoucement bar #1190)
• Add missing background-color definition on root (If you set either foreground or background color by default, please also set the other #1418)
• Fix error on clipboard in combination with superfences (Adding superfences removes copy to clipboard #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.

[wilhelmer]

Shouldn't the search index be written to localStorage? Doesn't work for me, localStorage stays empty after performing a search.

[squidfunk]

I postponed that feature to the next beta due to other priorities in refactoring. Sorry for the inconvenience.

The main motivation behind this beta version is to find out whether things break downstream. It’s an entirely new code base.

[wilhelmer]

Ah okay, thanks for the info. Maybe a "Known Issues" list would help for things like that.

My main concern with v4 is the search performance, so I tested that first. Currently, there isn't much change in performance, but I know it willl be dramatically better once search index persistance is implemented.

[squidfunk]

@wilhelmer actually search should be better than in v4 already. I don’t know what you precisely mean when speaking of performance, as the search query performance should not have changed. What did change is the delay upon first focusing the search when the index is built. That’s now completely gone, as the index is built after the page has loaded. Persisting the index will only cut down on setup time, which should already be barely noticeable.

Furthermore prebuilt indexes are now supported.

[wilhelmer]

Yes, there is no freeze/delay anymore when opening search. However, if you immediately open search after page load (which is what I think many users will do), it still takes around 3-4 seconds on my very mediocre computer at work and with a ~8 MB search index before the search results appear.

I thought that with the local storage implementation, this 3-4 second delay will only occur on first visit, and from then on, search results are displayed immediately, since the index doesn't have be built anymore. Isn't that the idea?

[squidfunk]

I didn't know you have such a big search index. Great use case! Persisting the index in local storage will bring exactly as much improvement as reading a prebuilt index from browser cache. You can test it by enabling prebuilt indexes and ensuring that your webserver sends the correct cache headers, so your browser will cache search_index.json.

[squidfunk]

However, also note that local storage only allows for 5 MB of storage. I implemented a worker that uses LZ-based compression to compress the index before writing it to local storage which, however, will again increase the TTI regarding search because it needs to be uncompressed. Furthermore if your raw search_index.json is 8 MB, the serialized index will be even larger. Compression will save around 30-40%. It will probably not be possible to write a index of this size to local storage.

A probably better approach is what I already prototyped and called instant loading - clicks on internal links are intercepted, directly loaded in a single XHR call and then injected into the existing DOM. This will allow to keep the index while traversing the docs. This however will not work with a local deployment, as XHR will not work.

[squidfunk]

I benchmarked the packer again on Chrome (macOS) with the search index of the official Material docs which should be pretty much within the mean in regard to its size.

Compression

Compressing the index which is done in a worker thread after it was built (and thus without disrupting the main thread):

Original	Compressed	Time
780kb	85kb	330ms
1560kb	155kb	660ms
3120kb	280kb	1500ms

I think it is rather safe to extrapolate the results. If the original serialized index is 8MB in size, it could be compressed to around 800kb in probably around 4 seconds. Maybe more on other browsers. The index must then be transferred back to the main thread and persisted in local storage which should probably add another second. This, however, is only done when the index could not be retrieved from local storage.

Decompression

Decompression is the actual thing we're interested in.

Original	Compressed	Time
780kb	85kb	75ms
1560kb	155kb	120ms
3120kb	280kb	170ms

Again, for a serialized index of 8MB in size we should be clocking in at around 500ms. While this looks pretty good, we have to account for the actual loading of the index which should be quite quick but definitely add some time + time for transfer to the main thread. However, I guess it could be under a second which should be pretty good.

I'll consider adding the packer back before the RC. I remembered the benchmarks to be worse, but it looks quite promising.

[squidfunk]

BTW, one problem which I have no solution for is the invalidation of the locally persisted index. I have no idea what we could use to determine whether the index needs to be rebuilt. What we could do is persist it in session storage, not local storage. This would ensure that it is purged in-between sessions but even that may not be enough.

[wilhelmer]

Maybe hash the index when the site is built and compare the hash on each page load?