Mkdocs-material: 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]

• [ ] Provide a link to donate to @squidfunk so he can order pizza and have more time for coding

[squidfunk]

@wilhelmer nice idea 😁 I actually already thought about it. However, listening to the latest React Podcast with Kitze I learned that having a Donate button will probably not help you fund the work of your project. People don’t tend to donate for something that they can already use for free which is why I decided not to include one.

[wilhelmer]

Well you‘d get at least 1 pizza, better than nothing 😄

[facelessuser]

1 🍕 > 0 🍕

Yup, checks out.

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

[squidfunk]

I took the time and implemented instant loading as can be seen in the latest version of refactor/rxjs-typescript. All internal links that are not anchors (i.e. #...) are intercepted and dispatched via XHR. Then, the new components are extracted from the parsed response, replaced in the DOM and all downstream observables/listeners are re-bound.

Works pretty well already and it's super fast! v5 will add instant loading as an experimental feature similar to tabs. Some open questions remain, e.g. what to do with Google Analytics, Disqus and custom JavaScript but it should all be solvable.

[wilhelmer]

I had to look up what instant loading is, but now that I know: Sounds great! 👏🏻

[squidfunk]

@wilhelmer don’t really know what to call it. There’s this JavaScript library called Turbolinks which does something similar but that does sound very Wordpressy.

[Stanzilla]

Do you want tickets for v5 bugs yet?

I only found two small problems so far:

• https://github.com/squidfunk/mkdocs-material/blob/refactor/rxjs-typescript/src/base.html#L422 this will cause a console error, needs src="{{ 'assets/javascripts/app.js' | url }}"
• I think https://github.com/squidfunk/mkdocs-material/blob/refactor/rxjs-typescript/src/assets/javascripts/index.ts#L92 should be as string[] and then https://github.com/squidfunk/mkdocs-material/blob/refactor/rxjs-typescript/src/assets/javascripts/index.ts#L132 names as [] just started learning TS though.

[squidfunk]

@Stanzilla thanks for checking it out already. For now just post your findings here. If we hit beta / release candidate, we can open a separate issue and maybe project to keep track of things without flooding the issue tracker.

https://github.com/squidfunk/mkdocs-material/blob/refactor/rxjs-typescript/src/base.html#L422 this will cause a console error, needs src="{{ 'assets/javascripts/app.js' | url }}"

What do you mean exactly? It's dependent on the app.js script, that's correct. Same behavior as before, except everything exported by the script is exported into the global variable app. I think of probably exporting all watch* functions into the global namespace but haven't decided yet.

I think https://github.com/squidfunk/mkdocs-material/blob/refactor/rxjs-typescript/src/assets/javascripts/index.ts#L92 should be as string[] and then > https://github.com/squidfunk/mkdocs-material/blob/refactor/rxjs-typescript/src/assets/javascripts/index.ts#L132 names as [] just started learning TS though.

Thanks for catching them. Typings are ongoing :-) The component union type must be put somewhere else, will fix the typings then. Maybe don't focus on the code base (e.g. typing errors) right now but on the functionality because I sometimes commit stuff that is not quite ready yet / needs work, but the branch is WIP anyway.

How does the instant loading work for you? I think it works pretty great already, though a little jittery when skimming through the browser history. Still trying to map out how to smoothen things out.

[Stanzilla]

Alright! And I was getting some "app is not defined" errors before but I just checked again and they are gone, sorry!

Functionality is pretty nice atm, I haven't checked which of my workarounds from v4 I can drop, I made some to workaround the collapse issue for examples. Also I edited the partial so I can have external links open in a new window instead, that currently causes a few JS errors in the console. Is that something you would like to support natively in the future? Maybe as a parameter from mkdocs.yml?

[squidfunk]

Functionality is pretty nice atm, I haven't checked which of my workarounds from v4 I can drop, I made some to workaround the collapse issue for examples.

The collapse issue (will) be fixed completely as we'll now listen on the change event and not click like in v4.

Also I edited the partial so I can have external links open in a new window instead, that currently causes a few JS errors in the console.

Good to know, will look into it. CMD + Click should not be intercepted but open in a new tab as expected.

Is that something you would like to support natively in the future? Maybe as a parameter from mkdocs.yml?

Nope, we removed it for UX reasons. It's however super easy to add the behavior in v5 via custom JavaScript that runs automatically, probably something like:

merge(load$, switch$)
  .subscribe(document => {
    document.querySelectorAll("a").forEach(el => {
      el.setAttribute("target", "_blank")
    })
  })

... whereas load$ (initial render) and switch$ (subsequent render) are exposed by the application.

[Stanzilla]

That's slightly less ugly than my

{% if nav_item.title == "A" or nav_item.title == "B" %}
    <a
      href="{{ nav_item.url | url }}"
      title="{{ nav_item.title | striptags }}"
      class="md-nav__link" target="_blank"
    >
    {% else %}
    <a
      href="{{ nav_item.url | url }}"
      title="{{ nav_item.title | striptags }}"
      class="md-nav__link"
    >
    {% endif %}
      {{ nav_item.title }}
    </a>

:D

Oh and I had to add the webpack copy plugin back for a custom JS file.

[squidfunk]

I moved everything that is unnecessary out of Webpack into the Makefile for much faster subsequent builds, as the Makefile correctly tracks dependencies and does not recompile everything upon a single change. Also copying, removing and replacing stuff is now entirely handled by the good ol' friends of UNIX.

[Stanzilla]

Just thought about the external links thing again, would still love to see that come back as an option because I'd still have to flag certain links with manual edits in the template for your JS solution to work properly.

[squidfunk]

The only external links that are added directly through Material are those in the footer and the source link. The Navigation is entirely local, so it should open in the same window. Furthermore, opening something in a new window is bad UX, as it's not transparent to the user. For this reason I can definitely say it's not coming back, I'm sorry.

[Stanzilla]

Yeah I just want to open social links and the edit one in a new window

[markallasread]

* [ ]  Provide a link to donate to @squidfunk so he can order pizza and have more time for coding

Not-so-much that there'll be more time for coding, just that we can compensate you for your contributions. I don't expect more by donating, I already received everything I need! :)

[squidfunk]

@wilhelmer @markallasread I started an Amazon wish list – in case somebody wants to give something back. 😊

[outofphase]

@squidfunk the wish list link takes me to amazon.com...are you in the US?

[squidfunk]

@outofphase nope, Germany. You're correct. I'll fix it and migrate it to Amazon Germany.

[squidfunk]

Migrated the lis to my German account and fixed the link above, can you check again?

[outofphase]

Yes that's worked, although not surprisingly everything is now in German which made navigating through the Amazon maze a little tricky for me. I really hope that I haven't just started a 30 day free trial of Amazon Prime. With luck you should get the book by the XKCD guy on Weds.

I think that one of the Amazon prompts was saying "buying from somewhere else?" which I should have clicked, but that also was in German so I wasn't sure. You should probably give guidance about that for non-German speakers.

[squidfunk]

@outofphase thanks a lot, that's super nice! 😊

Changing the wish list locale doesn't seem to be possible according to a StackExchange post which I find to be very strange. When I created the wish list on the .com domain, all shippings would have been from America which would mean astronomical shipping cost, so I think in the end this is the better option. As I have a German Amazon account I'm not prompted with the question you received, so don't really know what guidance to give 😐If somebody encounters this, a PR to the README would be super awesome, where I also added this link.

[coliff]

You could preset the locale to English with the URL: https://www.amazon.de/hz/wishlist/ls/U7LAO2O62KBU?language=en_US&sort=default
That'd make things a bit easier for non-German/English speakers. There is a change language option at the top of all Amazon sites though (to the right of the sidebar), so I think most people shouldn't have a problem...

[squidfunk]

@coliff thanks! Interestingly, en_US drops be back into German, but en seems to work.

[wilhelmer]

@coliff thanks! Interestingly, en_US drops be back into German, but en seems to work.

This is probably because technically, all five major Amazon EU sites (de, gb, es, it, fr) are on the same platform, while Amazon US is a totally different thing. So en is attributed to the GB site, while en_US is unknown to Amazon EU.

[squidfunk]

@wilhelmer thanks for the explanation. I just hope that en will cater to most cases.

[wilhelmer]

Enjoy your Masterminds of Programming ... und frohe Weihnachten :-)

[squidfunk]

@wilhelmer wow, thanks a lot! I will post a pic on Twitter within the next days showing what I received from you guys 😊meanwhile I'm working on v5, hope to finish an RC this year.

[wilhelmer]

You're welcome! It's a used copy, but in "excellent" condition. Let me know if there are any issues with that. I really don't want to cheap out, but I had very good experiences with these so-called "used" books in mint condition.

[squidfunk]

Some years ago, I bought a used copy of _The Tao of Programming_ from 1987 which was (and still is) in perfect shape, so no remorse!

[squidfunk]

Just rolled out a 5.0.0-preview. It would be awesome to collect some feedback here, so if you have some time over the holiday, give it a spin! 😊This release is focused on the new search.

Note that I'm on vacation from Dec 25 to Jan 9.

[wilhelmer]

Omg christmas came early! Thanks! Super excited. Won’t have enough time during the holidays, but will definitely provide feedback before your return on Jan 9.

[Stanzilla]

random observation:

• css-mqpacker has been deprecated

[squidfunk]

@Stanzilla was thinking about removing it anyway, as it may introduce indeterminism due to the re-ordering it does.

[Stanzilla]

Okay and what would you say is the best way of introducing custom files that need to be copied from node_modules to the material dir now, without reintroducing copy-webpack-plugin. Just manually copy them in the makefile?

[squidfunk]

@Stanzilla my recommendation would be to do it exactly like in the new Makefile.

If you want to copy files one-by-one:

https://github.com/squidfunk/mkdocs-material/blob/c736cd9939e1e208b4836cc8e305cafb14173ecf/Makefile#L73-L78

If you want to copy a whole directory:

https://github.com/squidfunk/mkdocs-material/blob/c736cd9939e1e208b4836cc8e305cafb14173ecf/Makefile#L89-L93

[squidfunk]

After replacing FontAwesome with SVGs, I'm also thinking about ditching the Material Icon font for the same. Could be quite tricky with the Admonition styles though, as they would need to be inlined in the CSS and SASS doesn't provide any filesystem helpers, but could be worth it.

Any thoughts?

[squidfunk]

9d67cdfe adds support for custom repository icons – it can now be set to any FontAwesome icon. The new default is brands/git-alt:

config:
  extra:
    repo_icon: brands/gitkraken

[squidfunk]

Just released 5.0.0-preview.2. Merry Christmas!

[Stanzilla]

Only just now noticed that they are killing TSLint https://github.com/palantir/tslint/issues/4534

[squidfunk]

@Stanzilla I'm aware of TSLint being deprecated. I also tried to switch to ESLint for v5, but it seemed that the support is not quite there yet. I may try this again in the future, but for now it is TSLint. As linting is (mostly) a matter of style, we can introduce ESLint after v5 without breaking anything.

[Stanzilla]

Currently the compilation fails if you don't prefix social links with "brand/", might be something to fix to ease migration.

  <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ social.type }}" class="md-tabs__link md-tabs__social">{% include "assets/images/icons/fontawesome/" ~ social.type ~ ".svg" %}</a>
      File "/usr/lib/python3/dist-packages/jinja2/loaders.py", line 187, in get_source
        raise TemplateNotFound(template)
    jinja2.exceptions.TemplateNotFound: assets/images/icons/fontawesome/discord.svg

[squidfunk]

It's gonna be a breaking change which will be part of the upgrade guide lines. I don't think we should default to brands.

[wilhelmer]

As discussed in https://github.com/mkdocs/mkdocs/pull/1805, Material v5 breaks support for mkdocs-localsearch.

To support the plugin and enable local search (file:// protocol), I most probably need changes on your side.

The following code works without any changes on mkdocs-localsearch (hooray), but is probably super bad since I have no experience with RxJS at all.

You'll have to change the ajax() call in index.ts to:

const data$ = new Observable<AjaxResponse>()

if (window.shim_searchIndex) {
  data$ = ajax({
    url: ``
  })
    .pipe(
      map(response => {
        response.response = window.shim_searchIndex
        return response
      })
    )
      .pipe<SearchIndexOptions>(
        pluck("response")
      )
}  
else {
  data$ = ajax({
    url: `${config.base}/search/search_index.json`,
    responseType: "json",
    withCredentials: true
  })
    .pipe<SearchIndexOptions>(
      pluck("response")
    )
}

If mkdocs-localsearch is not installed or enabled, the theme works as before. What do you think?

[squidfunk]

@wilhelmer would it work, if we provide a configuration option that is a function returning a promise resolving with the search index? You would only need to change the initialization of the theme:

app = initialize({
  ...
  search: {
    index: () => Promise.resolve(window.shim_searchIndex)
  }
  ...
})

Internally, the theme will use the promise returned by the function instead of the XHR call.

[wilhelmer]

Sounds good, but that needs changes on index.ts too, right? If you provide the full code, I'd be happy to test it.

[wilhelmer]

Only tested my solution in FF – sadly, Chrome causes more problems :-(

Chrome doesn't allow web workers locally. For more info and a solution, see https://stackoverflow.com/questions/21408510/chrome-cant-load-web-worker

In our solution (see this PR), we used the worker-loader package with the option inline set to true to get around that. I think that option has the same effect as the solution posted on Stack Overflow.

[squidfunk]

Sounds good, but that needs changes on index.ts too, right? If you provide the full code, I'd be happy to test it.

@wilhelmer yes, this was only the general idea. We could also define a new block called config in the base.html template which allows for easier overriding of the configuration.

In our solution (see this PR), we used the worker-loader package with the option inline set to true to get around that. I think that option has the same effect as the solution posted on Stack Overflow.

Inlining web workers would blow up the main application bundle and lead to a longer FMP. I'm also not using the worker-loader because it led to problems with the TypeScript typings and is not necessary. The current solution uses multiple Webpack entrypoints with the same result. If you need inlining, you could fork the theme and override the Webpack configuration.

I'm sorry but we cannot optimize the theme for entirely local execution. It's an edge case which affects probably less than 1% of users. However, I'm happy to provide hooks and mechanisms to help you achieve a better solution than monkey-patching fetch. Providing a new template block to change the configuration and a new option for the configuration to load the index from a different source (i.e. the promise) should help you achieve exactly what you want.

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