mdbook-infisearch
mdbook-infisearch
is a simple search plugin replacement for mdBook to use InfiSearch’s search interface and library instead of elasticlunr.js.
What, why?
MdBook already has its own built-in search function utilising elasticlunr, which works well enough for most cases. This plugin was mainly created as:
- A proof-of-concept to integrate InfiSearch with other static site generators easily
- A personal means to set up document deployment workflows in CI scripts
You may nonetheless want to use this plugin if you need InfiSearch’s extra features. Some examples:
- you require PDF file support, or JSON file support to link to out-of-domain pages.
- spelling correction, automatic prefix search, term proximity ranking, etc.
Styling
This plugin uses the css variables provided by the 5 main default themes in mdBook to style the search user interface. Switch the themes in this documentation to try out the different themes!
Note: The default InfiSearch theme is not included in the plugin. To see the default styling, head on over to the styling page or view the demo site.
Installation
Install the executable either using cargo install mdbook-infisearch
, or download and add the binaries to your PATH
manually.
Then, minimally add the first two configuration sections below to your book.toml
configuration file:
[output.html.search]
# disable the default mdBook search feature implementation
enable = false
[preprocessor.infisearch]
command = "mdbook-infisearch"
[output.infisearch] # this header should be added
# Plugin configuration options (optional)
# See search configuration page, or use the buttons below
mode = "target"
# Relative path to a InfiSearch indexer configuration file from the project directory.
#
# If you are creating this for the first time, let this point to a non-existent file
# and the config file will be created with Infisearch's settings tailored for mdBook.
config = "infi_search.json"
Preview
Use the following (non-canonical, documentation specific) buttons to try out the different mode
parameters.
You can also try out the different themes on this documentation using mdBook’s paintbrush icon!