Gracefully disable search on file:// if Worker initialization fails

[renoger]

I checked that...

• ... the documentation does not mention anything about my problem
• ... the problem doesn't occur with the default MkDocs template
• ... the problem is not in any of my customizations (CSS, JS, template)
• ... there are no open or closed issues that are related to my problem

Description

I was using v4.x without any of issues, but once I upgraded to v5 RCs (tried all 3) my navigation bars (both left and right) seem to not be fixed anymore, but rather move out of the frame when I scroll down. Please have a look at .gif attached.

One thing that might help understand the problem is that this issues only occurs when I run the built .html offline. When I use locolhost and "mkdocs serve", this behaviour does not occur.

Expected behavior

The navigation shall always be visible, as it was for me in v4.x.

Actual behavior

When I scroll down my page the navigation is not there anymore.

Steps to reproduce the bug

1. install any v5 RC
2. mkdocs build any configuration
3. run the static .hmtl e.g. in Chrome

Package versions

• Python: 3.7.0
• MkDocs: 1.1
• Material: 5.0.0rc3

Project configuration

site_name: MkDocs
site_url: https://www.mkdocs.org
site_description: Project documentation with Markdown.
site_author: MkDocs Team

repo_url: https://github.com/mkdocs/mkdocs/
edit_uri: ""

theme:
    name: 'material'
    highlightjs: true
    hljs_languages:
        - yaml
        - django
    feature: 
        
      

nav:
    - Home: index.md
    - User Guide:
        - Writing Your Docs: user-guide/writing-your-docs.md
        - Styling Your Docs: user-guide/styling-your-docs.md
        - Configuration: user-guide/configuration.md
        - Deploying Your Docs: user-guide/deploying-your-docs.md
        - Custom Themes: user-guide/custom-themes.md
        - Plugins: user-guide/plugins.md
    - About:
        - Release Notes: about/release-notes.md
        - Contributing: about/contributing.md
        - License: about/license.md

extra_css:
    - css/extra.css

markdown_extensions:
    - toc:
        permalink: false
    - admonition
    - def_list


copyright: Copyright &copy; 2014 <a href="https://twitter.com/_tomchristie">Tom Christie</a>, Maintained by the <a href="/about/release-notes/#maintenance-team">MkDocs Team</a>.
google_analytics: ['UA-27795084-5', 'mkdocs.org']

System information

• OS: Win10
• Browser: Chrome 80.0.3987.149

[squidfunk]

Could you try to disable the search plugin? Add the following to mkdocs.yml:

plugins: []

[renoger]

Thanks for your quick response!
I´ve added the line but it does not make any difference, unfortunately.

[squidfunk]

The problem manifests in v5 as the search worker script is initialized before the sidebars. Before it was the other way round so the JavaScript failed after sidebar initialization. On a general note, running this theme without a webserver may still exhibit some problems, but it is also not considered a very high priority. I'll try to provide a fix before the final release but can't say for sure.

What you can do in the meantime is switch to the the localsearch plugin (note that you need to use the material-v5 branch) and use my iframe-worker package to provide a Worker polyfill for file:// to get search running locally. This should hopefully fix the problem for now. Maybe @wilhelmer can shed some light on how to configure localsearch together with iframe-worker because it might have changed since the last time we spoke.

[renoger]

Ok, I guess I´ll wait a few more weeks as it´s not urgent for me. I actually used localsearch with 4.x without any problems, but also saw that @wilhelmer is working on an update of the plugin for v5.

Thanks for the great work!

[wilhelmer]

Just released mkdocs-localsearch, version 0.6.0, with Material v5 support and installation instructions for Material v5 themes.

Let me know if there are any issues. The promise_delay option is nothing but the good old setTimeout() monkey patch. We should get rid of that as soon possible, but it's the best we have right now.

[squidfunk]

Thanks for the clarification. From your docs:

Create a new file, save it in your project dir as theme/partials/header.html, and add the following content:

I guess this should be theme/main.html 😉

[wilhelmer]

True, copy/paste error from the v4 docs ;-) Will fix that.

[renoger]

Thanks for the quick turnaround!

However, I wasn´t successful yet. I installed your updated plugin and get the following error message:
FileNotFoundError: [Errno 2] No such file or directory: 'C:\Users\...\site\search\search_index.json'

If I go back to 0.5.0 this error does not occur, but also I´m back to the previous state (i.e. search not working, side bars not fixed).

I´m sure the error is on my side, but I think I´ve done everything as described.

[wilhelmer]

In mkdocs.yml, the search entry must be placed before localsearch:

plugins:
    - search
    - localsearch

Sorry, my fault. I'll update the docs.

[renoger]

Great, that did the trick. No more error messages and the the side bars stay in place :)

Only the search function itself is not working for me now. (When I´ve started typing it still says "Type to start searching" and on Enter nothing happens).

It doesn´t work neither with the local iframe-worker.js nor via the web link.
How can I help debug?

edit: please ignore the above, I found that it was due to a leftover .html file in my partials/lanuguage folder. It´s working now, awesome!

[squidfunk]

dac469e will now gracefully hide the search bar if:

1. The XMLHTTPRequest fails
2. The Worker initialization fails

Both are true when browsing locally. 1) can be mitigated by using the localsearch plugin as discussed in the documentation, 2) can be mitigated by using iframe-worker, as described in the localsearch documentation. However, now, locally, there's no console warning and the rest of the application should behave as expected.

We can release this as part of the next release, and when I find some time I will refactor the workaround, but for now it should be fine.

[squidfunk]

Released as part of 5.1.2

[ktomk]

@squidfunk no idea if it is a regression, building with mkdocs-material 5.5.12 the search was not hidden while using file:/// and seeing the webworker errors in the browser console. Not an issue for me tough: adding mkdocs-localsearch which works fine.

[squidfunk]

Thanks for reporting. Please open a new issue, if this turns out to be a problem. It would be perfect if you could try to find out which version introduced the problem, that would make fixing very quick and easy 😊

[ktomk]

Sorry I could not bisect that. That's maybe not so much of a bad news, as it means that with many of the releases since then, I had no further problems. As said I'm plugging in mkdocs-localsearch (thumbs up!). And the Makefile I use does not have a parameter for the mkdocs version (yet?), minimum requirements are per requirements.txt and I constantly shift towards the latest.

So unless you (or anyone else) pokes me specifically about looking for where for this, I would continue in my own projects pace, but would be happy to dive into it deeper, again, in case this gets raised.

Saying this, if there is traction for offline support in mkdocs usptream, also count on me for some legwork and support. But this needs decision in upstream.mkdocs (for me upstream is both mkdocs-material and mkdocs and I'm grateful how well both play together), and this is a bit off-topic here for this issue.

So other users should feel free to comment here with the version they run into the issue as then this is a concrete problem for someone and we can capture it in a more structured fashion. As you write this is much easier.

Currently "works on my machine" ;)

[squidfunk]

@ktomk no worries, thanks for your offer to help! I think there's no need for action right now.