A MkDocs plugin to make the native "search" plugin work locally (file:// protocol).
NOTE: This plugin only works with the Material for MkDocs theme. If you need support for other themes, feel free to create a pull request.
To use the plugin with Material v5 projects:
- Install the plugin using pip:
pip install mkdocs-localsearch
- Activate the plugin in
mkdocs.yml
, in addition to thesearch
plugin:plugins: - search - localsearch
- Make sure that the
use_directory_urls
setting is set tofalse
inmkdocs.yml
to have filenames in the URL (required when using the file:/// protocol). - Add a
custom_dir
entry to thetheme
section inmkdocs.yml
:theme: name: material custom_dir: theme
- Create a new file, save it in your project dir as
theme/main.html
, and add the following content:Note: Don't use the{% extends "base.html" %} {% block config %} {% if "localsearch" in config["plugins"] %} <script src="https://unpkg.com/iframe-worker/polyfill"></script> <script src="{{ 'search/search_index.js' | url }}"></script> {% endif %} {% endblock %}
extra_javascript
option inmkdocs.yml
to add the two scripts above. Scripts referenced viaextra_javascript
are placed at the bottom of the HTML page, i.e., after the search implementation, which is too late. - If your documentation should work offline, i.e., without internet access:
- Open this file and save it as
iframe-worker.js
in yourdocs_dir
.
Example path:docs/assets/javascripts/iframe-worker.js
- Edit
theme/main.html
and change the following line:to this:<script src="https://unpkg.com/iframe-worker/polyfill"></script>
<script src="{{ 'assets/javascripts/iframe-worker.js' | url }}"></script>
- Open this file and save it as
- If your project has a large search index (several MBytes), add the
promise_delay
setting:A delay of 100 ms worked with a search index of 24 MB (prebuilt index).plugins: - search - localsearch: promise_delay: 100
Note that thepromise_delay
setting has a negative effect on performance (loading time will be increased).
To use the plugin with Material v4 projects:
- Install version 0.5.0 of the plugin using pip:
pip install mkdocs-localsearch==0.5.0
- Activate the plugin in
mkdocs.yml
:plugins: - localsearch
- Add
search_index.js
to theextra_javascript
section inmkdocs.yml
:extra_javascript: - search/search_index.js
- Add a
custom_dir
entry to thetheme
section inmkdocs.yml
:theme: name: material custom_dir: theme
- Open this file and save it in your project dir as
theme/partials/header.html
. - Edit
theme/partials/header.html
and change the following line:
{% if "search" in config["plugins"] %}
to this:
{% if "localsearch" in config["plugins"] %}
- Done!