A MkDocs plugin to make the native "search" plugin work locally (file:// protocol).
This plugin only works with the Material for MkDocs theme. If you need support for other themes, feel free to create a pull request.
If you are using Material v9 or later, this plugin is not necessary. Use the inbuilt offline
plugin instead.
:warning: Plugin not working anymore? On Nov 3, 2022, the URL given in steps 5 and 6 below changed from "iframe-worker/polyfill" to "iframe-worker/shim". Update
theme/main.html
if necessary.
To use the plugin with Material v7 or v8 projects:
pip install mkdocs-localsearch
mkdocs.yml
, in addition to the search
plugin:
plugins:
- search
- localsearch
use_directory_urls
is set to false
in mkdocs.yml
.custom_dir
entry to the theme
section in mkdocs.yml
:
theme:
name: material
custom_dir: theme
theme/main.html
, and add the following content:
{% extends "base.html" %}
{% block config %}
{{ super() }}
{% if "localsearch" in config["plugins"] %}
<script src="https://unpkg.com/iframe-worker/shim"></script>
<script src="https://github.com/wilhelmer/mkdocs-localsearch/raw/master/{{ 'search/search_index.js' | url }}"></script>
{% endif %}
{% endblock %}
Note: Don't use the extra_javascript
option in mkdocs.yml
to add the two scripts above. Scripts referenced via extra_javascript
are placed at the bottom of the HTML page, i.e., after the search implementation, which is too late.
iframe-worker.js
in your docs_dir
.docs/assets/javascripts/iframe-worker.js
theme/main.html
and change the following line:
<script src="https://unpkg.com/iframe-worker/shim"></script>
to this:
<script src="https://github.com/wilhelmer/mkdocs-localsearch/raw/master/{{ 'assets/javascripts/iframe-worker.js' | url }}"></script>
To use the plugin with Material v5 or v6 projects:
pip install mkdocs-localsearch==0.7.0
mkdocs.yml
, in addition to the search
plugin:
plugins:
- search
- localsearch
use_directory_urls
is set to false
in mkdocs.yml
.custom_dir
entry to the theme
section in mkdocs.yml
:
theme:
name: material
custom_dir: theme
theme/main.html
, and add the following content:
{% extends "base.html" %}
{% block config %}
{% if "localsearch" in config["plugins"] %}
<script src="https://unpkg.com/iframe-worker/shim"></script>
<script src="https://github.com/wilhelmer/mkdocs-localsearch/raw/master/{{ 'search/search_index.js' | url }}"></script>
{% endif %}
{% endblock %}
Note: Don't use the extra_javascript
option in mkdocs.yml
to add the two scripts above. Scripts referenced via extra_javascript
are placed at the bottom of the HTML page, i.e., after the search implementation, which is too late.
iframe-worker.js
in your docs_dir
.docs/assets/javascripts/iframe-worker.js
theme/main.html
and change the following line:
<script src="https://unpkg.com/iframe-worker/shim"></script>
to this:
<script src="https://github.com/wilhelmer/mkdocs-localsearch/raw/master/{{ 'assets/javascripts/iframe-worker.js' | url }}"></script>
promise_delay
setting:
plugins:
- search
- localsearch:
promise_delay: 100
A delay of 100 ms worked with a search index of 24 MB (prebuilt index).
Note that the promise_delay
setting has a negative effect on performance (loading time will be increased).
To use the plugin with Material v4 projects:
pip install mkdocs-localsearch==0.5.0
mkdocs.yml
:
plugins:
- localsearch
search_index.js
to the extra_javascript
section in mkdocs.yml
:
extra_javascript:
- search/search_index.js
custom_dir
entry to the theme
section in mkdocs.yml
:
theme:
name: material
custom_dir: theme
theme/partials/header.html
.theme/partials/header.html
and change the following line:{% if "search" in config["plugins"] %}
{% if "localsearch" in config["plugins"] %}