Search with Elasticlunr, updated (#604)

* Add search with elasticlunr.js

This commit adds search functionality to mdBook, based on work done by @Phaiax. The in-browser search code uses elasticlunr.js to execute the search, using an index generated at book build time by elasticlunr-rs.

* Add generator comment
Someone on Reddit was wondering how the rust book was generated and said they checked the source. Thought I'd put this here. Might be a good idea to have a little footer "made with mdBook", but this'll do for now.

* Remove search/editor file override behavior

* Use for loop for book iterator

* Improve HTML regex

* Fix search CORS in file URIs

* Use ammonia to sanitize HTML

* Filter html5ever log messages

Author: mattico

.gitattributes

@@ -2,3 +2,7 @@
 
 * text=auto eol=lf
 *.rs rust
+*.woff -text
+*.ttf -text
+*.otf -text
+*.png -text

Cargo.lock

@@ -50,6 +50,10 @@ iron = { version = "0.5", optional = true }
 staticfile = { version = "0.4", optional = true }
 ws = { version = "0.7", optional = true}
 
+# Search feature
+elasticlunr-rs = { version = "0.2", optional = true }
+ammonia = { version = "1.1", optional = true }
+
 [build-dependencies]
 error-chain = "0.11"
 
@@ -60,12 +64,13 @@ walkdir = "2.0"
 pulldown-cmark-to-cmark = "1.1.0"
 
 [features]
-default = ["output", "watch", "serve"]
+default = ["output", "watch", "serve", "search"]
 debug = []
 output = []
 regenerate-css = []
 watch = ["notify", "time", "crossbeam"]
 serve = ["iron", "staticfile", "ws"]
+search = ["elasticlunr-rs", "ammonia"]
 
 [[bin]]
 doc = false

Cargo.toml

@@ -8,3 +8,12 @@ mathjax-support = true
 
 [output.html.playpen]
 editable = true
+
+[output.html.search]
+limit-results = 20
+use-boolean-and = true
+boost-title = 2
+boost-hierarchy = 2
+boost-paragraph = 1
+expand = true
+heading-split-level = 2

book-example/book.toml

@@ -16,6 +16,9 @@ create-missing = false
 
 [output.html]
 additional-css = ["custom.css"]
+
+[output.html.search]
+limit-results = 15
 ```
 
 ## Supported configuration options
@@ -81,14 +84,48 @@ The following configuration options are available:
   stylesheets that will be loaded after the default ones where you can
   surgically change the style.
 - **additional-js:** If you need to add some behaviour to your book without
-  removing the current behaviour, you can specify a set of javascript files
+  removing the current behaviour, you can specify a set of JavaScript files
   that will be loaded alongside the default one.
-- **playpen:** A subtable for configuring various playpen settings.
-- **no-section-label**: mdBook by defaults adds section label in table of
+- **no-section-label:** mdBook by defaults adds section label in table of
   contents column. For example, "1.", "2.1". Set this option to true to
   disable those labels. Defaults to `false`.
-
-**book.toml**
+- **playpen:** A subtable for configuring various playpen settings.
+- **search:** A subtable for configuring the in-browser search
+  functionality. mdBook must be compiled with the `search` feature enabled
+  (on by default).
+
+Available configuration options for the `[output.html.playpen]` table:
+
+- **editable:** Allow editing the source code. Defaults to `false`.
+- **copy-js:** Copy JavaScript files for the editor to the output directory.
+  Defaults to `true`.
+
+[Ace]: https://ace.c9.io/
+
+Available configuration options for the `[output.html.search]` table:
+
+- **limit-results:** The maximum number of search results. Defaults to `30`.
+- **teaser-word-count:** The number of words used for a search result teaser. 
+  Defaults to `30`.
+- **use-boolean-and:** Define the logical link between multiple search words. 
+  If true, all search words must appear in each result. Defaults to `true`.
+- **boost-title:** Boost factor for the search result score if a search word
+  appears in the header. Defaults to `2`.
+- **boost-hierarchy:** Boost factor for the search result score if a search
+  word appears in the hierarchy. The hierarchy contains all titles of the
+  parent documents and all parent headings. Defaults to `1`.
+- **boost-paragraph:** Boost factor for the search result score if a search 
+  word appears in the text. Defaults to `1`.
+- **expand:** True if search should match longer results e.g. search `micro` 
+  should match `microwave`. Defaults to `true`.
+- **heading-split-level:** Search results will link to a section of the document
+  which contains the result. Documents are split into sections by headings
+  this level or less.
+  Defaults to `3`. (`### This is a level 3 heading`)
+- **copy-js:** Copy JavaScript files for the search implementation to the
+  output directory. Defaults to `true`.
+
+This shows all available options in the **book.toml**:
 ```toml
 [book]
 title = "Example book"
@@ -105,6 +142,18 @@ additional-js = ["custom.js"]
 [output.html.playpen]
 editor = "./path/to/editor"
 editable = false
+
+[output.html.search]
+enable = true
+searcher = "./path/to/searcher"
+limit-results = 30
+teaser-word-count = 30
+use-boolean-and = true
+boost-title = 2
+boost-hierarchy = 1
+boost-paragraph = 1
+expand = true
+heading-split-level = 3
 ```
 
 
@@ -145,4 +194,4 @@ override the book's title without needing to touch your `book.toml`.
 
 The latter case may be useful in situations where `mdbook` is invoked
 from a script or CI, where it sometimes isn't possible to update the
-`book.toml` before building.
+`book.toml` before building.

book-example/src/format/config.md

@@ -14,3 +14,5 @@ If you have contributed to mdBook and I forgot to add you, don't hesitate to add
 - [Michael-F-Bryan](https://github.com/Michael-F-Bryan)
 - [Chris Spiegel](https://github.com/cspiegel)
 - [projektir](https://github.com/projektir)
+- [Phaiax](https://github.com/Phaiax)
+- [Matt Ickstadt](https://github.com/mattico)

book-example/src/misc/contributors.md

@@ -3,13 +3,15 @@
 set -ex
 
 main() {
+    cross build --target $TARGET --all --no-default-features
     cross build --target $TARGET --all
     cross build --target $TARGET --all --release
 
     if [ ! -z $DISABLE_TESTS ]; then
         return
     fi
 
+    cross test --target $TARGET --no-default-features
     cross test --target $TARGET
     cross test --target $TARGET --release
 }

ci/script.sh

@@ -92,6 +92,8 @@ fn init_logger() {
     } else {
         // if no RUST_LOG provided, default to logging at the Info level
         builder.filter(None, LevelFilter::Info);
+        // Filter extraneous html5ever not-implemented messages
+        builder.filter(Some("html5ever"), LevelFilter::Error);
     }
 
     builder.init();