Material 5.0.0 Status

TL;DR This issue is meant for updates and discussions on the progress of the rework of the theme. Please feel free to checkout and try the refactor/rxjs-typescript branch and comment on the current state of development.

Description

The last major releases of Material for MkDocs were mainly issued for compatibility reasons. While version 2 and 3 were related to backward incompatible changes of MkDocs (0.17.1 and 1.0 respectively), version 4 was released due to backward incompatible changes related to users with Chinese system languages (#911). The next iteration, version 5, is a substantial rewrite of the underlying JavaScript functionality to a TypeScript and RxJS-based architecture. This will yield the following major benefits:

1. All features that are provided by the theme (e.g. the sidebars, tabs, search, etc.) will be observable by 3rd party JavaScript. This allows for very easy extension and customization. This will address issues like #1102 where users want to extend the functionality of the theme without re-compiling or forking it. Also, disabling functionality should be easier.

2. Improving search performance. Search will be moved to a web worker and exhibit better caching and re-building behavior. This will mitigate problems were the UI freezes due to large search indexes which pre-building on the server-side only partly solves. Furthermore, search will be re-architected to fit into the plugin concept introduced by MkDocs 1.x.

3. Color customization will be re-implemented using CSS variables. Changing the color to your custom brand colors will be even simpler and the theme will become smaller (as the palette CSS file will not be necessary anymore). Support for CSS variables is pretty great by now, but there are some browsers that don’t support it, respectively IE 11, Opera mini, QQ browser and Baidu browser. These browsers will receive a (probably neutral) fallback color. If you must support those browsers, you can still extend the theme and customize the build will custom CSS colors as already described in the customization guide.

There might also be some slight face lifting, but the main aspects of Material 5 is the introduction of a more modern architecture. The rewrite will also make the theme testable, so unit tests can and will be written to ensure functionality.

I will document my progress here and there will be a beta phase similar to before the release of 1.0.0 (#46). Some lists with things that need to be done will follow.

Evaluate

• ~Consider flexsearch as an alternative to lunr.js~

TODOs

5.0

General

• Move everything except JavaScript compilation out of Webpack into Makefile
• Rewrite Webpack configuration in TypeScript
• Setup TypeScript project structure
• Implement experimental instant loading
• Add a plugin section to the docs
• Rewrite all components to new architecture
• Check browser support before release

Functionality

General

• Polyfill <details>/<summary> functionality
• Wrap all data tables for better overflow scrolling
• Automatically open <details> after child-anchor jump
• Automatically open <details> before printing
• Automatically close drawer on anchor jump
• General keyboard handlers
• Clipboard.js integration
• Cleanup code block CSS

Scroll-related

• Toggle header shadow on scroll
• Toggle header title swap on scroll
• Toggle hero visibility on scroll
• Toggle tabs visibility on scroll

Sidebars

• Position sidebar with navigation
• Position sidebar with table of contents
• Blur links in table of contents
• Apply scrollfix for active navigation for iOS
• Collapse/expand nested navigation

Search

• Move search into web worker (currently w/o fallback, do we need one?)
• Persist search index in local storage see https://github.com/squidfunk/mkdocs-material/issues/1465#issuecomment-588286846
• Compress search index see https://github.com/squidfunk/mkdocs-material/issues/1465#issuecomment-588286846
• Focus input after form reset
• Focus input after opening search
• Focus query if search is open and character is typed
• Add (multi-)language support
• Search keyboard handlers
• Fix margin / spacing of search bar if no source repository is given
• Lock body for active search on mobile

Accessibility

• Handle tabbing context for better accessibility
• Reset tabbing behavior

Repository

• Make repository icon configurable
• Retrieve facts for the given repository
• Render repository information

Issues

• Add ‘selected’ as toc item state (#1102)
• Update Font Awesome to LATEST (#756)
• Fix rendering issues in table of contents (#1292)
• Fixed meta title and description only rendering first character bug (#1324)
• Add announcement bar (#1190)
• Update Material icons to LATEST (#1174)
• Add missing background-color definition on root (#1418)
• Fix error on clipboard in combination with superfences (#1440)
• Refactor color customization to use CSS variables (#1297)
• Fix navigation CTRL-click issues (#1177)
• Decide on main footer block (#1351)

5.x

• Add dark mode (#1305)
• Add dark mode automatism via prefers-color-scheme (#1266)

[squidfunk]

Making progress, most stuff is functional. I’ll try hard to push out an RC in the middle of next week! The small facelift will also include a new logo:

[squidfunk]

I started to document my progress regarding the rewrite of the current features in the original post.

Furthermore I think I finally got the grasp of RxJS and boy, is it beautiful. If somebody has some experience with RxJS, I would really appreciate some comments on the architecture I’m building on the refactor/rxjs-typescript branch. See this folder.

After migrating everything to RxJS, implementing instant loading (aka “turbolinks” which I prototyped three years (!) ago here) will be a breeze, as re-binding components will be super easy. This would also greatly improve search UX, as the page will more or less behave like an SPA, and thus the search index has to be built only once.