Material 5.0.0 Status

[squidfunk]

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

• [x] ~Consider flexsearch as an alternative to lunr.js~

TODOs

5.0

General

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

Functionality

General

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

Scroll-related

• [x] Toggle header shadow on scroll
• [x] Toggle header title swap on scroll
• [x] Toggle hero visibility on scroll
• [x] Toggle tabs visibility on scroll

Sidebars

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

Search

• [x] 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
• [x] Focus input after form reset
• [x] Focus input after opening search
• [x] Focus query if search is open and character is typed
• [x] Add (multi-)language support
• [x] Search keyboard handlers
• [x] Fix margin / spacing of search bar if no source repository is given
• [x] Lock body for active search on mobile

Accessibility

• [x] Handle tabbing context for better accessibility
• [x] Reset tabbing behavior

Repository

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

Issues

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

5.x

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

[wilhelmer]

Thanks for your support. I‘m not sure what to do now – if I have to fork the theme anyway for Chrome support, the localsearch plugin is pointless because I‘ll be better off integrating all necessary modifications in the fork. I need to think about that ...

[squidfunk]

@wilhelmer we can look into a fallback for web workers after v5 is out. I think the only thing we need to do is to add some compatibility layer to the web worker code which detects whether the web worker runs in a separate thread or in the main thread and provide a compatibility layer for postMessage. Should be pretty straight forward.

Or maybe a polyfill like nolanlawson/pseudo-worker?

[wilhelmer]

@squidfunk Okay, I'll open an issue as soon as v5 is out. Do you have any idea when that will be? Preview 2 looks pretty stable to me already, apart from IE11 compatibility, but I don't know if you even planned to make it IE compatible (wouldn't mind if you didn't).

[AlexWayfer]

apart from IE11 compatibility

1. IE11 is still active, supported. Without new features, but with fixes (the last version was released 29 days ago according to Wikipedia). And it'll, I guess, while Windows 10 is live.
2. IE11 is still more than 1% of usage according to Can I use.

[squidfunk]

@wilhelmer I'll try to have a feature-complete and deployable RC by the end of January. From there on it'll probably be another 2-4 weeks until we hit a stable state.

@AlexWayfer haven't tested IE yet. CSS variables will not work in IE which Material v5 will introduce. We need to provide fallback (or compat) CSS which will show the theme in neutral or default colors. We'll do that post-RC.

[squidfunk]

As a side note: IE usage on the official Material for MkDocs site for the last year was at 0,26% which should be quite representative (50k unique users). IE usage among developers seems to be much less frequent that overall IE usage.

[Stanzilla]

Would not bother with a fallback, imo

[kemistep]

please enhance chinese search ; the search and toc is very userful

[squidfunk]

@ministp support for lunr-languages is still missing, that's correct. I added an item to the task list in the original post and will add it back before the RC.

[squidfunk]

018e38e9 adds back support for lunr-languages. Note than the search language and okenization must now be configured through plugins.search.lang and plugins.search.separator, a described in the official docs

[squidfunk]

I started a migration guide for v5, documenting the changes that are necessary to the templates and partials if the user has overridden them in their build here. Those changes are crucial for the new (and more future-proof) application structure. I will also add another section on configuration changes and customization such as colors etc. In general the overall structure did not change much, especially custom CSS should continue to work in 99% of the cases.

I'm also hoping to finish the missing features within the next days, so we can put out a fully working RC. Sorry for the delay, quite hard to find some spare time at the moment.

[Stanzilla]

For me, the build process changes were/are the biggest hurdle, might be worth mentioning as well!

[squidfunk]

@Stanzilla What specifically would be worth mentioning? Would you mind writing down the hurdles you experienced?

[Stanzilla]

The move from webpack to the makefile, I have a few custom things in the webpack config and the new structure was a bit confusing to me, also probably less Windows friendly. I also sometimes have to npm clean before I can build because it does not see changes even though I did them

[squidfunk]

If you could isolate what files do not get rebuilt when changed we can fix the Makefile

[Stanzilla]

If you could isolate what files do not get rebuilt when changed we can fix the Makefile

I just remembered, webpack config changes. If I do build, change something webpack.config.ts and then build again, it does nothing.

[squidfunk]

@Stanzilla should be fixed with 9b9527f8 – but I'm pretty sure that Webpack config changes are also not picked up on master.

[squidfunk]

Small update: took the afternoon and finished the keyboard handlers (general and search-related) and copy-to-clipboard integration. Needs some cleanup (the main index.ts is a mess), but should be functionally working. For the clipboard message we'll switch to a snackbar/toast design, deprecating the message next to the button. Furthermore the clipboard buttons now have a proper outline on focus which is better for accessibility. I'll cleanup the main index.ts when the RC is out and all functionality has been implemented.

[squidfunk]

... and we're back to Webpack as of b486d0be. I ditched the whole Makefile-based approach. For a project the size of Material compatibility is an important issue and I ran into problems with asset versioning etc. where I would've had to build a lot of stuff from scratch. It just makes no sense. Sorry for any confusion this has caused with forks.

[Stanzilla]

Yay!

[squidfunk]

Small facelifting of Admonitions in a018ed02:

Before:

After:

[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:

[facelessuser]

Looks nice!

[squidfunk]

Fixed a lot of stuff today including some long standing errors. @facelessuser you're the only one I know of who is running the dev build in production. Could I ask you to update to the latest version to see if something breaks?

Bugs fixed in refactoring branch:

• Fixed anchor jump from mobile search – a399540940848d66ccab6f7aa9913b35b015ca11
• Fixed search body lock on mobile – a399540940848d66ccab6f7aa9913b35b015ca11

Bugs fixed which are still in current master:

• Fixed header shadow disappearing on iOS Safari – a539eab0b5efe37a7b008b8c9458ebf19028769d, 694eaca889ffedb109eb7159009f29d04ab79b3c
• Fixed lines wrapping in code blocks on iOS Safari and Safari – a6b22a44619f375e38573f21e0685fd666695d93
• Fixed permalink characters (i.e. ¶) being part of textContent. This should hopefully solve the problem that some search engines index them and add them to the search summary – ca260e0fafa3a8b6e172368a0bcee6aa11b78fa0

New features not in master:

• Added scroll snapping for navigation and toc – 67406d26eb6b1bf8d5594ec08534b80b44a7929c
• Added scroll snapping for search – 9fe7c62d779b65bc36779e4f454da2ee2d6f1c44
• Revamped code block line number styles – a6b22a44619f375e38573f21e0685fd666695d93

[facelessuser]

Yeah, I'll try it out and get back to you later today or tomorrow.

[facelessuser]

@squidfunk, seems to be working for me. Nothing obvious seems broken.

[squidfunk]

Thanks for your support. I‘m not sure what to do now – if I have to fork the theme anyway for Chrome support, the localsearch plugin is pointless because I‘ll be better off integrating all necessary modifications in the fork. I need to think about that ...

@wilhelmer I made some steps towards a solution for making localsearch work with v5 in fdffefd5. It's now possible to pass a Promise resolving with the contents of search_index.json which would allow for the technique we discussed before: inlining the search_index.json into the template via a meta tag, retrieving it from there and passing it explicitly.

What remains is making the Worker work locally. I tried pseudo-worker and it would work if it didn't make an XHR request to retrieve and eval the worker script. However, when I replace the Worker with PseudoWorker in a hosted non-local context, it works perfectly in the main thread.

Thus, inlining the search_index.json and mimicking the API of Worker are IMHO the only things necessary to make it work. We can probably tackle that after the final release of v5. To mimic the worker API, we would need to implement addEventListener, postMessage and importScripts. We could probably do this by wrapping the Worker constructor and implement the following logic:

1. Add a new script to the end of document.body which makes a copy of self (which equals window in the main thread), so we can restore it later. Furthermore, overwrite self with our custom implementations of the three functions mentioned above. Basically, we only need to hook up the function passed to addEventListener to postMessage and we should be good to go.

2. Now add another new script with the URL of the web worker. It will hook into our new self pseudo worker and setup everything. We could probably just use the pseudo-worker implementation. For all scripts passed to importScripts, add another synchronously script to the DOM to mimic the behavior.

3. Add another script which restores self to window. Then, after evaluating all scripts, it's probably safe to remove them all.

[wilhelmer]

Thanks for your effort! I created https://github.com/squidfunk/mkdocs-material/issues/1464 just while you typed this 😄

I hope we can continue the discussion there. I won't be able to do the coding myself, but my colleague will join in.

[squidfunk]

Just released Material 5.0.0b1. See #1465. Would be awesome to get some feedback, especially on the brand new search. Please report any problems, issues or incompatibilities in the linked issue.

[squidfunk]

Just released Material 5.0.0b2. See #1469. Again, would be great to get some feedback, and finally a new feature - instant loading!

[squidfunk]

Besides a brand new logo, v5 will include a new default (fav)icon to better reflect the core values of Material: Documentation for people

[mnogue]

Much better than the other one. I love it!

[squidfunk]

@mnogue it's only the default icon, though 😊Changeable with a single line of code. The official docs will however include the new logo I posted earlier.

[squidfunk]

🎉Beta 3 just landed in #1483 and since we're feature complete, I'm closing this issue. I would encourage everybody to test the latest beta, as it's the last one before the final RC. There's still some cleaning up to do, but there's not much to change after beta 3. The more people test it, the earlier we can roll out a release candidate and finally get v5 out of the door!