mkdocs-localsearch

A MkDocs plugin to replace the native "search" plugin with a search plugin that also works locally (file:// protocol). Only works with the Material theme.


Keywords
mkdocs, local, search
License
MIT
Install
pip install mkdocs-localsearch==0.4.0

Documentation

mkdocs-localsearch

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.

Installation (Material v9)

If you are using Material v9 or later, this plugin is not necessary. Use the inbuilt offline plugin instead.

Installation (Material v7 or v8)

⚠️ 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:

  1. Install the plugin using pip: pip install mkdocs-localsearch
  2. Activate the plugin in mkdocs.yml, in addition to the search plugin:
    plugins:
        - search
        - localsearch
  3. Make sure that use_directory_urls is set to false in mkdocs.yml.
  4. Add a custom_dir entry to the theme section in mkdocs.yml:
    theme:
        name: material
        custom_dir: theme
  5. Create a new file, save it in your project dir as 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="{{ '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.
  6. If your documentation should work offline, i.e., without internet access:
    1. Open this file and save it as iframe-worker.js in your docs_dir.
      Example path: docs/assets/javascripts/iframe-worker.js
    2. Edit theme/main.html and change the following line:
      <script src="https://unpkg.com/iframe-worker/shim"></script>
      to this:
      <script src="{{ 'assets/javascripts/iframe-worker.js' | url }}"></script>

Installation (Material v5 or v6)

To use the plugin with Material v5 or v6 projects:

  1. Install version 0.7.0 of the plugin using pip: pip install mkdocs-localsearch==0.7.0
  2. Activate the plugin in mkdocs.yml, in addition to the search plugin:
    plugins:
        - search
        - localsearch
  3. Make sure that use_directory_urls is set to false in mkdocs.yml.
  4. Add a custom_dir entry to the theme section in mkdocs.yml:
    theme:
        name: material
        custom_dir: theme
  5. Create a new file, save it in your project dir as 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="{{ '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.
  6. If your documentation should work offline, i.e., without internet access:
    1. Open this file and save it as iframe-worker.js in your docs_dir.
      Example path: docs/assets/javascripts/iframe-worker.js
    2. Edit theme/main.html and change the following line:
      <script src="https://unpkg.com/iframe-worker/shim"></script>
      to this:
      <script src="{{ 'assets/javascripts/iframe-worker.js' | url }}"></script>
  7. If your project has a large search index (several MBytes), add the 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).

Installation (Material v4)

To use the plugin with Material v4 projects:

  1. Install version 0.5.0 of the plugin using pip: pip install mkdocs-localsearch==0.5.0
  2. Activate the plugin in mkdocs.yml:
    plugins:
        - localsearch
  3. Add search_index.js to the extra_javascript section in mkdocs.yml:
    extra_javascript:
        - search/search_index.js
  4. Add a custom_dir entry to the theme section in mkdocs.yml:
    theme:
        name: material
        custom_dir: theme
  5. Open this file and save it in your project dir as theme/partials/header.html.
  6. Edit theme/partials/header.html and change the following line:
    {% if "search" in config["plugins"] %}
    to this:
    {% if "localsearch" in config["plugins"] %}