Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
5 tasks done
tl-dbg opened this issue Aug 5, 2022 · 4 comments
Closed
5 tasks done
Labels
change request Issue requests a new feature or improvement resolved Issue is resolved, yet unreleased if open

Comments

@tl-dbg
Copy link

tl-dbg commented Aug 5, 2022

Contribution guidelines

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

  • ... the problem doesn't occur with the mkdocs or readthedocs themes
  • ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
  • ... the documentation does not mention anything about my problem
  • ... 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

01e1ad56-e5cf-43f9-b78b-3b59e20d9948

98a3bfb1-14fd-4243-bbb9-3869406ac3a2

01829fb4-f3be-4010-b0e1-081a54427974

Firefox

fb176ca6-6458-4297-8102-3b4cd5ca2887

e8d56098-b2dd-4241-92f7-aa817f75eae3

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
Copy link
Owner

squidfunk commented Aug 6, 2022

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.

@squidfunk squidfunk added the needs investigation Issue must be investigated by the maintainers label Aug 6, 2022
@squidfunk squidfunk changed the title When opening the offline version document with file://schema, the main thread is blocked by the search plugin [insider]. Offline plugin: large sites freeze on initial load due to initializing search Aug 6, 2022
@tl-dbg
Copy link
Author

tl-dbg commented Aug 10, 2022

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
Copy link
Owner

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 squidfunk added change request Issue requests a new feature or improvement resolved Issue is resolved, yet unreleased if open and removed needs investigation Issue must be investigated by the maintainers labels Aug 13, 2022
@squidfunk
Copy link
Owner

Released as part of 8.4.0+insiders-4.21.1.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
change request Issue requests a new feature or improvement resolved Issue is resolved, yet unreleased if open
Projects
None yet
Development

No branches or pull requests

2 participants