mkdocs-izsam-search 0.1.9

MkDocs plugin to extend search functions

mkdocs-search-izsam

This MkDocs plugin enhances the native search functionality by:

• Enabling local search without CORS issues
• Indexing YAML metadata from Markdown files for improved search capabilities

Local Search Functionality

The plugin generates two JavaScript files—one for config and one for docs—which can be included in your theme as follows:

<script src="{{ 'search/search_config.js'|url }}"></script>
<script src="{{ 'search/search_docs.js'|url }}"></script>

This approach eliminates CORS issues typically encountered with loadJSON and the native worker.js model.

Important

To leverage these JavaScript files and bypass the native search worker, set the search_index_only option to true in your theme configuration:

theme:
  name: null
  custom_dir: your_custom_theme
  include_search_page: true
  search_index_only: true

Search Metadata YAML Support

The plugin indexes YAML metadata defined in your Markdown files, making these fields searchable. To exclude specific metadata keys from the search index, add an exclude_meta_keys entry to your file's metadata, listing the keys to ignore. For example:

exclude_meta_keys:
  - sections.type
  - sections.data.link

Setup

Install the plugin using pip:

pip install mkdocs-izsam-search

Activate the plugin in mkdocs.yml:

plugins:
  - izsam-search

It is possible to use same config options of the native search plugin:

- izsam-search:
        lang: en

You can then implement search using your preferred JavaScript library (for example, lunr.js). For more details, see the MkDocs documentation on search and themes.

See Also

Change log

[0.1.9] - 2025-09-08

Added metadata YAML searchability

• Implemented functionality to index and search metadata defined in markdown YAML front matter
• Documented usage and configuration in README.md

[0.1.8] - 2021-11-10

Implementation of the main feature: build .js files to allow local search and avoid CORS problems

• Added necessary code in plugin.py
• Added instruction on README.md

[0.1.7] - 2021-11-10

Configuration error

• Configuration error: mkdocs_izsam_search.search_index.SearchIndex must be a subclass of mkdocs.plugins.BasePlugin. Changed search_index.py

[0.1.6] - 2021-11-10

Configuration error

• Configuration error: mkdocs_izsam_search.search_index.SearchIndex must be a subclass of mkdocs.plugins.BasePlugin. Changed entry_points in setup.py

[0.1.5] - 2021-11-10

Setup

• different syntax for setup()

[0.1.4] - 2021-11-10

Setup

• entry_points declaration in setup()

[0.1.3] - 2021-11-10

Debug on MANIFEST.in

• Modified MANIFEST.in there was an error causing import data issues

[0.1.2] - 2021-11-10

Edited

• README.md

[0.0.1] - 2021-11-10

Added

• HISTORY.md