Offline plugin: large sites freeze on initial load due to initializing search

[tl-dbg]

Contribution guidelines

• [X] I've read the contribution guidelines and wholeheartedly agree

I've found a bug and checked that ...

• [X] ... the problem doesn't occur with the mkdocs or readthedocs themes
• [X] ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
• [X] ... the documentation does not mention anything about my problem
• [X] ... there are no open or closed issues that are related to my problem

Description

I want to use more than 1000 files offline in our project. This search_index file size is more than 10MB. When opening the offline documents with the file://schema, the main thread is blocked by the search plugin, and I have to wait. Probably a browser implementation issue, not a problem with Mkdocs for Materials itself.

Is there a workaround for this problem or any way to delay the search initialization, such as focusing on the search windows and then initializing it?

Consideration

The Material for Mkdocs search plugin is implemented as a Web Worker and works fine online. But offline, Chrome and Firefox cannot start the Web Worker with the file://, so every time a page is opened, the initialization of the search function blocks the main thread. This block makes the navigation operation delayed. 

Performance of a small number of files(offline) Performance of a large number of files(offline) Performance of a large number of files(offline) that hosted on an http server

Chrome

Firefox

From this performance, it appears that,

• In the case of http://, there is no problem with the offline version, but only in the case of file://, the threads are not separated.

I am not sure, but due to a combination of browser implementations, is WebWorker not working as intended in the case of file://?

Expected behaviour

The navigation can be opened offline with file:// as well as with http:// without delay.

Actual behaviour

The navigation is delayed when offline with file://.

Steps to reproduce

1. Create markdown files with a large number of pages.
2. Set the search and offline plugins and then run mkdocs build.
3. Open the HTML file from file://.

Package versions

• Python: Python 3.7.9
• MkDocs: version 1.3.0
• Material: mkdocs-material-insiders-8.2.16-insiders-4.16.2

Configuration

site_name: My Docs

theme:
  name: material

plugins:
  - search
  - offline

System information

• Operating system: Windows 10
• Browser: Chrome 103.0.5060.134

[squidfunk]

Thanks for reporting and the detailed analysis.

When serving via file://, browsers do not allow for parallel operations as web workers are not supported. This is why Material for MkDocs uses my little iframe-worker shim, that mimics web worker API but is effectively synchronous. As you have very large documentation, initialization is actually noticeable. We could theoretically defer search index initialization to the moment when the user clicks the search bar, which should at least mitigate the problem that the site always freezes on navigation. However, we will not be able to get rid of the fact that search initialization will freeze the main thread – it's not possible via file://. This is a limitation of browsers, not of Material for MkDocs.

[tl-dbg]

Thanks for the reply. As expected, it was a limitation of browsers.

I am considering making changes to the plugin code for our project. Could you please let me know if you know where and how to change the code I should modify to defer search index initialization to the moment when the user clicks the search bar? I know it won't be a fundamental fix, but I'm willing to try it if it would make things mitigate the problem.

[squidfunk]

Fixed in squidfunk/mkdocs-material-insiders@3724e19d5.

Now, if the protocol is file://, search initialization is deferred to the moment the search is clicked for the first time. This doesn't mitigate the freezing of the browser, but as noted in my previous comment it's not fixable due to how browsers work. Navigation (without search) should now feel quite smooth.

It's actually close to a miracle we could make search work on local browsing in the first place 😉

[squidfunk]

Released as part of 8.4.0+insiders-4.21.1.