Material for MkDocs v5 Preview
This is a preview release for what's coming in the next major release of Material for MkDocs. v5 is a complete rewrite of the underlying application logic and migration to a more modern and extensible architecture. It is based on TypeScript and RxJS and paves the way for deeper and easier customization through author-defined JavaScript. Additionally, all features have been rethought and rewritten and should inhibit much better performance.
This is a major rewrite. Before pushing this out the door, we would want to get some feedback on it. Nearly all features have been re-architected, so there might be things breaking unexpectedly or some edge cases to catch.
Features
All-new search
The search functionality 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. When the construction is finished, the built index is serialized and written to local storage from where it can be read on the next page load, cutting down on indexing time.
Additionally, most of lunr's query syntax is now supported, e.g.:
color -primary +accent
Easier theme extension
By adding JavaScript via extra_javascript (see the guide on customization), one can now subscribe to the application state, e.g. subscribe to everything that is sent to the search index:
app.state.search.query$.subscribe(console.log)... or subscribe to the table of contents:
app.state.toc$.subscribe(console.log)Lighter FontAwesome integration
FontAwesome is now integrated via inline SVGs. The configuration must now mirror FontAwesome's folder structure:
extra:
social:
- type: brand/twitter
link: '...'
- type: regular/globe
link: '...'Usage
This release is by no means considered stable, but only meant for testing. Some features are still missing, but they will be implemented before an official release candidate is released (probably) at the end of January.
Currently missing features:
- Search language integration (i.e.
lunr-languages) - Clipboard.js integration
- Keyboard handlers
- Pre-print handlers
- UI/UX fixes for iOS
- Repository information loading
- Accessibility optimization (tabbing)
For a detailed list, see this issue.
To test this release, the best idea is to check the refactor/rxjs-typescript branch out from GitHub and point your mkdocs.yml's theme.custom_dir to the respective folder, see this link. You are encouraged to provide feedback, especially rearding the new search in #1306!