Removed a deprecation warning

The former has been deprecated in favor of the latter

.gitattributes

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

.gitignore

@@ -1,4 +1,3 @@
-Cargo.lock
 target
 
 # MacOS temp file

.travis.yml

@@ -1,87 +1,46 @@
-# Based on the "trust" template v0.1.1
-# https://github.com/japaric/trust/tree/v0.1.1
-
-dist: trusty
 language: rust
-services: docker
-sudo: required
 
-cache: cargo
+cache: 
+  - cargo
+
 before_cache:
-- chmod -R a+r $HOME/.cargo
+  - chmod -R a+r $HOME/.cargo
 
 env:
   global:
-  - CRATE_NAME=mdbook
-  - secure: DPzSRXyfRIVTibv1wOKFeGekXlL8sumGEZxpeq911MpLlrndOKmOo5Ibi3JD8fbUOsE9A/5spj4B2KQNjhbplH+Cp26oEikjuNAA6cA/b2+/TMoC3i0klAYpVopBBV3FFna0gLP+q6t6fzG2v9TJrvmmVav6KVX6ylPNvD/LoReCjrkpgLIQuAQ6dSQNor9uV+EVt4plKhhkiS28DlYdgmTvNb5g4dzOhs8hoWty72J765VYWEDDC8qXn6N9GyrhsC3dhjASGn+1QDSCADYdbG9nrRlb4CZhrfcgOnHhAFva363kshg9HtCphigMgQy2oZXk4nLWK90/HuaPPkVj+N/lpIYjtiHOunToZJfIb0MWzyVI+7+I7WR6n6XbhLCPMe/sPXHHQ3HhQhZZ9xv7CDx9IkYJQBcF3LC+9kzJRi4QT0UTqrxcO3ncgXwvholP8Vg2KKPqFcbuyLPzbvr/o8zIilvLUFAEoDPfTEwSAC4BCzaGkFQVWzhWkgw8Pe1ckOEYFkZ0VLBuCpEiz+x45sbBL1SnnO5xhpjmdc572ZyW7ZmAABw1VfiWhhBWg4WGSf8lLnDHhNA36Qon34pnME/xpJQtWoo7ZZkkzvzYP/oW88/0UIMWDSOYKz7MijXlbNUggwAwUhrLzXDuB71HUKfPreFubfUxbOpu+OtTcOQ=
-
-matrix:
-  include:
-  # Android
-  - env: TARGET=arm-linux-androideabi DISABLE_TESTS=1
-
-  # Linux
-  - env: TARGET=aarch64-unknown-linux-gnu
-  - env: TARGET=arm-unknown-linux-gnueabi
-  - env: TARGET=i686-unknown-linux-gnu
-  - env: TARGET=x86_64-unknown-linux-gnu
-  - env: TARGET=x86_64-unknown-linux-musl
-
-  # Mac
-  # - env: TARGET=i686-apple-darwin
-  #   os: osx
-  # - env: TARGET=x86_64-apple-darwin
-  #   os: osx
-
-  # BSD
-  - env: TARGET=i686-unknown-freebsd DISABLE_TESTS=1
-  - env: TARGET=x86_64-unknown-freebsd DISABLE_TESTS=1
-  - env: TARGET=x86_64-unknown-netbsd DISABLE_TESTS=1
-
-  # Other channels
-  - env: TARGET=x86_64-unknown-linux-gnu
-    rust: beta
-  # - env: TARGET=x86_64-apple-darwin
-  #   os: osx
-  #   rust: beta
-  - env: TARGET=x86_64-unknown-linux-gnu
-    rust: nightly
-  # - env: TARGET=x86_64-apple-darwin
-  #   os: osx
-  #   rust: nightly
-
-before_install:
-- set -e
-- rustup self update
+    - CRATE_NAME=mdbook
+    - TARGET=x86_64-unknown-linux-gnu
 
 install:
-- sh ci/install.sh
-- source ~/.cargo/env || true
+  - sh ci/install.sh
+  - export PATH=$PATH:$HOME/.cargo/bin
 
 script:
-- bash ci/script.sh
+  - cargo build --all --no-default-features
+  - cargo build --verbose
+  - cargo test --verbose
 
 after_success:
-- bash ci/github_pages.sh
+  - bash ci/github_pages.sh
 
 before_deploy:
-- sh ci/before_deploy.sh
+  - sh ci/before_deploy.sh
 
 deploy:
+  provider: releases
   api_key:
-  - secure: cURRWBr034iqBz/ifD7uOunBfNR30YxIXfgLX0osWz+iafkVbhDGYYz9sBmRraqO2P7L2koEXMADVb/md1kI2+ykiq/ml+l9zuEAZPVmvSGUN7ZD+7s+lu3l5OBPG5z175T+b2q2q2m8XVR7TW20ra4QbE0bq06KAoOyjSgQVBTSCYsL9uTsGwiVRMEqqJT/BmKhKJNkpGsTKyBSKkOXvfeAAbE260vXUDEN9TYdJ3fvteRrpwLX56ee64gIZUq0RjDc4SKIEqilM6iUtNMvurqaewYNGkiXKRruV6BPCHxEHo6NNT46kOJLBJTf7gZw//dWhSoWpg9P0gdAnPWm407kSa3F7aJ1eRShAFQ4BLyfz9efTqm+jP3fOp7Mm7igSh9w6caSRuOnSsUf5+raRQ8E5Y9HsWGzzpZQk24Fx9EGZ04EeDSdpZAFz+jcbMpHf8t2p4CEx0CCNwYvKx6EydMKbMF5QteQ8SQkXNLhv7Rz2OgtXWYZPRVCMfQfOplsi2InsLCrQxTgwh+6u654SqVSgaHG+IncEAxBrdWy4rHcg7qereUcKfcY3k96vaDxdn/T2c00Ig0aNFR91YnixGMd6J6tQgDcRK9jh6fUm1CCBE9hT+pNUmtgYKuWBoLZexUZFFnfuBed0WciBot1bGDDamndqKq0jJiAzg+GMHk=
+    - secure: cURRWBr034iqBz/ifD7uOunBfNR30YxIXfgLX0osWz+iafkVbhDGYYz9sBmRraqO2P7L2koEXMADVb/md1kI2+ykiq/ml+l9zuEAZPVmvSGUN7ZD+7s+lu3l5OBPG5z175T+b2q2q2m8XVR7TW20ra4QbE0bq06KAoOyjSgQVBTSCYsL9uTsGwiVRMEqqJT/BmKhKJNkpGsTKyBSKkOXvfeAAbE260vXUDEN9TYdJ3fvteRrpwLX56ee64gIZUq0RjDc4SKIEqilM6iUtNMvurqaewYNGkiXKRruV6BPCHxEHo6NNT46kOJLBJTf7gZw//dWhSoWpg9P0gdAnPWm407kSa3F7aJ1eRShAFQ4BLyfz9efTqm+jP3fOp7Mm7igSh9w6caSRuOnSsUf5+raRQ8E5Y9HsWGzzpZQk24Fx9EGZ04EeDSdpZAFz+jcbMpHf8t2p4CEx0CCNwYvKx6EydMKbMF5QteQ8SQkXNLhv7Rz2OgtXWYZPRVCMfQfOplsi2InsLCrQxTgwh+6u654SqVSgaHG+IncEAxBrdWy4rHcg7qereUcKfcY3k96vaDxdn/T2c00Ig0aNFR91YnixGMd6J6tQgDcRK9jh6fUm1CCBE9hT+pNUmtgYKuWBoLZexUZFFnfuBed0WciBot1bGDDamndqKq0jJiAzg+GMHk=
   file_glob: true
   file: "$CRATE_NAME-$TRAVIS_TAG-$TARGET.*"
   on:
     condition: "$TRAVIS_RUST_VERSION = stable"
     tags: true
-  provider: releases
   skip_cleanup: true
 
 branches:
   only:
-  - "/^v\\d+\\.\\d+\\.\\d+.*$/"
-  - master
+    - "/^v\\d+\\.\\d+\\.\\d+.*$/"
+    - master
 
 notifications:
   email:

Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "mdbook"
-version = "0.1.0"
+version = "0.1.6"
 authors = ["Mathieu David <mathieudavid@mathieudavid.org>", "Michael-F-Bryan <michaelfbryan@gmail.com>"]
-description = "create books from markdown files (like Gitbook)"
+description = "Create books from markdown files"
 documentation = "http://rust-lang-nursery.github.io/mdBook/index.html"
 repository = "https://github.com/rust-lang-nursery/mdBook"
 keywords = ["book", "gitbook", "rustbook", "markdown"]
@@ -14,15 +14,20 @@ exclude = [
     "src/theme/stylus/**",
 ]
 
+[package.metadata.release]
+sign-commit = true
+push-remote = "origin"
+tag-prefix = "v"
+
 [dependencies]
 clap = "2.24"
 chrono = "0.4"
-handlebars = "0.29"
+handlebars = "0.32"
 serde = "1.0"
 serde_derive = "1.0"
 error-chain = "0.11"
 serde_json = "1.0"
-pulldown-cmark = "0.1"
+pulldown-cmark = "0.1.2"
 lazy_static = "1.0"
 log = "0.4"
 env_logger = "0.5.0-rc.1"
@@ -30,7 +35,7 @@ toml = "0.4"
 memchr = "2.0"
 open = "1.1"
 regex = "0.2.1"
-tempdir = "0.3.4"
+tempfile = "3.0"
 itertools = "0.7"
 shlex = "0.1"
 toml-query = "0.6"
@@ -41,30 +46,33 @@ time = { version = "0.1.34", optional = true }
 crossbeam = { version = "0.3", optional = true }
 
 # Serve feature
-iron = { version = "0.5", optional = true }
-staticfile = { version = "0.4", optional = true }
+iron = { version = "0.6", optional = true }
+staticfile = { version = "0.5", optional = true }
 ws = { version = "0.7", optional = true}
 
+# Search feature
+elasticlunr-rs = { version = "2.0", optional = true }
+ammonia = { version = "1.1", optional = true }
+
 [build-dependencies]
 error-chain = "0.11"
 
 [dev-dependencies]
 select = "0.4"
-pretty_assertions = "0.4"
+pretty_assertions = "0.5"
 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
 name = "mdbook"
 path = "src/bin/mdbook.rs"
-
-[workspace]
-members = ["book-example/src/for_developers/mdbook-wordcount"]

README.md

@@ -10,7 +10,7 @@
     <tr>
         <td><strong>Windows</strong></td>
         <td>
-            <a href="https://ci.appveyor.com/project/azerupi/mdbook/"><img src="https://ci.appveyor.com/api/projects/status/o38racsnbcospyc8/branch/master?svg=true"></a>
+            <a href="https://ci.appveyor.com/project/rust-lang-libs/mdbook"><img src="https://ci.appveyor.com/api/projects/status/ysyke2rvo85sni55?svg=true"></a>
         </td>
     </tr>
     <tr>
@@ -40,7 +40,7 @@ There are multiple ways to install mdBook.
    path to the binary into your `PATH`.
 
 2. **From Crates.io**
-j
+
    This requires [Rust] and Cargo to be installed. Once you have installed
    Rust, type the following in the terminal:
 
@@ -141,6 +141,10 @@ explanation, check out the [User Guide].
     `http://localhost:3000` (port is changeable) and reloads the browser when a
     change occurs.
 
+- `mdbook clean`
+
+    Delete directory in which generated book is located.
+
 
 ### As a library
 

book-example/book.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/src/SUMMARY.md

@@ -7,6 +7,7 @@
     - [watch](cli/watch.md)
     - [serve](cli/serve.md)
     - [test](cli/test.md)
+    - [clean](cli/clean.md)
 - [Format](format/format.md)
     - [SUMMARY.md](format/summary.md)
     - [Configuration](format/config.md)
@@ -15,7 +16,7 @@
         - [Syntax highlighting](format/theme/syntax-highlighting.md)
         - [Editor](format/theme/editor.md)
     - [MathJax Support](format/mathjax.md)
-    - [Rust code specific features](format/rust.md)
+    - [mdBook specific features](format/mdbook.md)
 - [For Developers](for_developers/index.md)
     - [Preprocessors](for_developers/preprocessors.md)
     - [Alternate Backends](for_developers/backends.md)

book-example/src/cli/build.md

@@ -14,8 +14,8 @@ convenience. Large books will therefore remain structured when rendered.
 
 #### Specify a directory
 
-Like `init`, the `build` command can take a directory as argument to use instead of the
-current working directory.
+Like `init`, the `build` command can take a directory as an argument to use
+instead of the current working directory.
 
 ```bash
 mdbook build path/to/book

book-example/src/cli/clean.md

@@ -0,0 +1,21 @@
+# The clean command
+
+The clean command is used to delete the generated book and any other build
+artifacts.
+
+```bash
+mdbook clean
+```
+
+It will try to delete the built book. If a path is provided, it will be used.
+
+#### Specify a directory
+
+Like `init`, the `clean` command can take a directory as an argument to use
+instead of the normal build directory.
+
+```bash
+mdbook clean --dest-dir=path/to/book
+```
+
+`path/to/book` could be absolute or relative.

book-example/src/cli/serve.md

@@ -6,8 +6,8 @@ This preferred by many for writing books with mdbook because it allows for you t
 
 #### Specify a directory
 
-Like `watch`, `serve` can take a directory as argument to use instead of the
-current working directory.
+Like `watch`, `serve` can take a directory as an argument to use instead of
+the current working directory.
 
 ```bash
 mdbook serve path/to/book
@@ -21,7 +21,7 @@ mdbook serve path/to/book
 For example: suppose you had an nginx server for SSL termination which has a public address of 192.168.1.100 on port 80 and proxied that to 127.0.0.1 on port 8000. To run use the nginx proxy do:
 
 ```bash
-mdbook server path/to/book -p 8000 -i 127.0.0.1 -a 192.168.1.100
+mdbook serve path/to/book -p 8000 -i 127.0.0.1 -a 192.168.1.100
 ```
 
 If you were to want live reloading for this you would need to proxy the websocket calls through nginx as well from `192.168.1.100:<WS_PORT>` to `127.0.0.1:<WS_PORT>`. The `-w` flag allows for the websocket port to be configured.

book-example/src/cli/watch.md

@@ -5,8 +5,8 @@ You could repeatedly issue `mdbook build` every time a file is changed. But usin
 
 #### Specify a directory
 
-Like `init` and `build`, `watch` can take a directory as argument to use instead of the
-current working directory.
+Like `init` and `build`, `watch` can take a directory as an argument to use
+instead of the current working directory.
 
 ```bash
 mdbook watch path/to/book

book-example/src/for_developers/backends.md

@@ -116,7 +116,7 @@ tables. If none are provided it'll fall back to using the default HTML
 renderer. 
 
 Notably, this means if you want to add your own custom backend you'll also
-need to make sure to add the HTML backend, even if its tabke just stays empty.
+need to make sure to add the HTML backend, even if its table just stays empty.
 
 Now you just need to build your book like normal, and everything should *Just 
 Work*.
@@ -149,7 +149,7 @@ The reason we didn't need to specify the full name/path of our `wordcount`
 backend is because `mdbook` will try to *infer* the program's name via 
 convention. The executable for the `foo` backend is typically called 
 `mdbook-foo`, with an associated `[output.foo]` entry in the `book.toml`. To
-explicitly tell `mdbook` what command to invoke (it may require command line 
+explicitly tell `mdbook` what command to invoke (it may require command-line 
 arguments or be an interpreted script), you can use the `command` field.
 
 ```diff
@@ -349,4 +349,4 @@ the source code or ask questions.
 [`Book`]: http://rust-lang-nursery.github.io/mdBook/mdbook/book/struct.Book.html
 [`Book::iter()`]: http://rust-lang-nursery.github.io/mdBook/mdbook/book/struct.Book.html#method.iter
 [`Config`]: http://rust-lang-nursery.github.io/mdBook/mdbook/config/struct.Config.html 
-[issue tracker]: https://github.com/rust-lang-nursery/mdBook/issues
+[issue tracker]: https://github.com/rust-lang-nursery/mdBook/issues

book-example/src/for_developers/index.md

@@ -21,7 +21,7 @@ The process of rendering a book project goes through several steps.
 
 1. Load the book 
     - Parse the `book.toml`, falling back to the default `Config` if it doesn't
-       exist.
+       exist
     - Load the book chapters into memory
     - Discover which preprocessors/backends should be used
 2. Run the preprocessors
@@ -43,4 +43,4 @@ explanation on the configuration system.
 
 [`MDBook`]: http://rust-lang-nursery.github.io/mdBook/mdbook/book/struct.MDBook.html
 [API Docs]: http://rust-lang-nursery.github.io/mdBook/mdbook/
-[config]: file:///home/michael/Documents/forks/mdBook/target/doc/mdbook/config/index.html
+[config]: file:///home/michael/Documents/forks/mdBook/target/doc/mdbook/config/index.html

book-example/src/for_developers/mdbook-wordcount/Cargo.toml

@@ -2,9 +2,8 @@
 name = "mdbook-wordcount"
 version = "0.1.0"
 authors = ["Michael Bryan <michaelfbryan@gmail.com>"]
-workspace = "../../../.."
 
 [dependencies]
-mdbook = { path = "../../../.." }
+mdbook = { path = "../../../..", version = "*" }
 serde = "1.0"
 serde_derive = "1.0"

book-example/src/for_developers/preprocessors.md

@@ -5,13 +5,13 @@ book is loaded and before it gets rendered, allowing you to update and mutate
 the book. Possible use cases are:
 
 - Creating custom helpers like `\{{#include /path/to/file.md}}`
-- Updating links so `[some chapter](some_chapter.md)` is automatically changed 
+- Updating links so `[some chapter](some_chapter.md)` is automatically changed
   to `[some chapter](some_chapter.html)` for the HTML renderer
-- Substituting in latex-style expressions (`$$ \frac{1}{3} $$`) with their 
+- Substituting in latex-style expressions (`$$ \frac{1}{3} $$`) with their
   mathjax equivalents
 
 
-## Implementing a Preprocessor 
+## Implementing a Preprocessor
 
 A preprocessor is represented by the `Preprocessor` trait.
 
@@ -29,4 +29,68 @@ pub struct PreprocessorContext {
     pub root: PathBuf,
     pub config: Config,
 }
-```
+```
+
+## A complete Example
+
+The magic happens within the `run(...)` method of the [`Preprocessor`][preprocessor-docs] trait implementation.
+
+As direct access to the chapters is not possible, you will probably end up iterating
+them using `for_each_mut(...)`:
+
+```rust
+book.for_each_mut(|item: &mut BookItem| {
+    if let BookItem::Chapter(ref mut chapter) = *item {
+      eprintln!("{}: processing chapter '{}'", self.name(), chapter.name);
+      res = Some(
+          match Deemphasize::remove_emphasis(&mut num_removed_items, chapter) {
+              Ok(md) => {
+                  chapter.content = md;
+                  Ok(())
+              }
+              Err(err) => Err(err),
+          },
+      );
+  }
+});
+```
+
+The `chapter.content` is just a markdown formatted string, and you will have to
+process it in some way. Even though it's entirely possible to implement some sort of
+manual find & replace operation, if that feels too unsafe you can use [`pulldown-cmark`][pc]
+to parse the string into events and work on them instead.
+
+Finally you can use [`pulldown-cmark-to-cmark`][pctc] to transform these events back to
+a string.
+
+The following code block shows how to remove all emphasis from markdown, and do so
+safely.
+
+```rust
+fn remove_emphasis(num_removed_items: &mut i32, chapter: &mut Chapter) -> Result<String> {
+    let mut buf = String::with_capacity(chapter.content.len());
+    let events = Parser::new(&chapter.content).filter(|e| {
+        let should_keep = match *e {
+            Event::Start(Tag::Emphasis)
+            | Event::Start(Tag::Strong)
+            | Event::End(Tag::Emphasis)
+            | Event::End(Tag::Strong) => false,
+            _ => true,
+        };
+        if !should_keep {
+            *num_removed_items += 1;
+        }
+        should_keep
+    });
+    cmark(events, &mut buf, None)
+        .map(|_| buf)
+        .map_err(|err| Error::from(format!("Markdown serialization failed: {}", err)))
+}
+```
+
+For everything else, have a look [at the complete example][example].
+
+[preprocessor-docs]: https://docs.rs/mdbook/0.1.3/mdbook/preprocess/trait.Preprocessor.html
+[pc]: https://crates.io/crates/pulldown-cmark
+[pctc]: https://crates.io/crates/pulldown-cmark-to-cmark
+[example]: https://github.com/rust-lang-nursery/mdBook/blob/master/examples/de-emphasize.rs

book-example/src/format/config.md

@@ -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`.
+- **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).
 
-**book.toml**
+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,12 +142,24 @@ 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
 ```
 
 
 ## Environment Variables
 
-All configuration values van be overridden from the command line by setting the
+All configuration values can be overridden from the command line by setting the
 corresponding environment variable. Because many operating systems restrict
 environment variables to be alphanumeric characters or `_`, the configuration
 key needs to be formatted slightly differently to the normal `foo.bar.baz` form.
@@ -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/mdbook.md

@@ -0,0 +1,64 @@
+# mdBook-specific markdown
+
+## Hiding code lines
+
+There is a feature in mdBook that lets you hide code lines by prepending them with a `#`.
+
+```bash
+# fn main() {
+    let x = 5;
+    let y = 6;
+
+    println!("{}", x + y);
+# }
+```
+
+Will render as
+
+```rust
+# fn main() {
+    let x = 5;
+    let y = 7;
+
+    println!("{}", x + y);
+# }
+```
+
+## Including files
+
+With the following syntax, you can include files into your book:
+
+```hbs
+\{{#include file.rs}}
+```
+
+The path to the file has to be relative from the current source file.
+
+Usually, this command is used for including code snippets and examples. In this case, oftens one would include a specific part of the file e.g. which only contains the relevant lines for the example. We support four different modes of partial includes:
+
+```hbs
+\{{#include file.rs:2}}
+\{{#include file.rs::10}}
+\{{#include file.rs:2:}}
+\{{#include file.rs:2:10}}
+```
+
+The first command only includes the second line from file `file.rs`. The second command includes all lines up to line 10, i.e. the lines from 11 till the end of the file are omitted. The third command includes all lines from line 2, i.e. the first line is omitted. The last command includes the excerpt of `file.rs` consisting of lines 2 to 10.
+
+## Inserting runnable Rust files
+
+With the following syntax, you can insert runnable Rust files into your book:
+
+```hbs
+\{{#playpen file.rs}}
+```
+
+The path to the Rust file has to be relative from the current source file.
+
+When play is clicked, the code snippet will be sent to the [Rust Playpen] to be compiled and run. The result is sent back and displayed directly underneath the code.
+
+Here is what a rendered code snippet looks like:
+
+{{#playpen example.rs}}
+
+[Rust Playpen]: https://play.rust-lang.org/

book-example/src/format/rust.md

@@ -1,44 +0,0 @@
-# Rust code specific features
-
-## Hiding code lines
-
-There is a feature in mdBook that let's you hide code lines by prepending them with a `#`.
-
-```bash
-# fn main() {
-    let x = 5;
-    let y = 6;
-
-    println!("{}", x + y);
-# }
-```
-
-Will render as
-
-```rust
-# fn main() {
-    let x = 5;
-    let y = 7;
-
-    println!("{}", x + y);
-# }
-```
-
-
-## Inserting runnable Rust files
-
-With the following syntax, you can insert runnable Rust files into your book:
-
-```hbs
-\{{#playpen file.rs}}
-```
-
-The path to the Rust file has to be relative from the current source file.
-
-When play is clicked, the code snippet will be send to the [Rust Playpen] to be compiled and run. The result is send back and displayed directly underneath the code.
-
-Here is what a rendered code snippet looks like:
-
-{{#playpen example.rs}}
-
-[Rust Playpen]: https://play.rust-lang.org/

book-example/src/misc/contributors.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)

ci/before_deploy.sh

@@ -15,11 +15,9 @@ main() {
             ;;
     esac
 
-    test -f Cargo.lock || cargo generate-lockfile
+    cargo rustc --bin mdbook --target $TARGET --release -- -C lto
 
-    cross rustc --bin mdbook --target $TARGET --release -- -C lto
-
-    cp target/$TARGET/release/mdbook $stage/
+    cp target/release/mdbook $stage/
 
     cd $stage
     tar czf $src/$CRATE_NAME-$TRAVIS_TAG-$TARGET.tar.gz *
@@ -28,4 +26,4 @@ main() {
     rm -rf $stage
 }
 
-main
+main

ci/script.sh

@@ -1,20 +0,0 @@
-# This script takes care of testing your crate
-
-set -ex
-
-main() {
-    cross build --target $TARGET --all
-    cross build --target $TARGET --all --release
-
-    if [ ! -z $DISABLE_TESTS ]; then
-        return
-    fi
-
-    cross test --target $TARGET
-    cross test --target $TARGET --release
-}
-
-# we don't run the "test phase" when doing deploys
-if [ -z $TRAVIS_TAG ]; then
-    main
-fi

examples/de-emphasize.rs

@@ -0,0 +1,94 @@
+//! This program removes all forms of emphasis from the markdown of the book.
+extern crate mdbook;
+extern crate pulldown_cmark;
+extern crate pulldown_cmark_to_cmark;
+
+use mdbook::errors::{Error, Result};
+use mdbook::MDBook;
+use mdbook::book::{Book, BookItem, Chapter};
+use mdbook::preprocess::{Preprocessor, PreprocessorContext};
+use pulldown_cmark::{Event, Parser, Tag};
+use pulldown_cmark_to_cmark::fmt::cmark;
+
+use std::ffi::OsString;
+use std::env::{args, args_os};
+use std::process;
+
+struct Deemphasize;
+
+impl Preprocessor for Deemphasize {
+    fn name(&self) -> &str {
+        "md-links-to-html-links"
+    }
+
+    fn run(&self, _ctx: &PreprocessorContext, book: &mut Book) -> Result<()> {
+        eprintln!("Running '{}' preprocessor", self.name());
+        let mut res: Option<_> = None;
+        let mut num_removed_items = 0;
+        book.for_each_mut(|item: &mut BookItem| {
+            if let Some(Err(_)) = res {
+                return;
+            }
+            if let BookItem::Chapter(ref mut chapter) = *item {
+                eprintln!("{}: processing chapter '{}'", self.name(), chapter.name);
+                res = Some(
+                    match Deemphasize::remove_emphasis(&mut num_removed_items, chapter) {
+                        Ok(md) => {
+                            chapter.content = md;
+                            Ok(())
+                        }
+                        Err(err) => Err(err),
+                    },
+                );
+            }
+        });
+        eprintln!(
+            "{}: removed {} events from markdown stream.",
+            self.name(),
+            num_removed_items
+        );
+        match res {
+            Some(res) => res,
+            None => Ok(()),
+        }
+    }
+}
+
+fn do_it(book: OsString) -> Result<()> {
+    let mut book = MDBook::load(book)?;
+    book.with_preprecessor(Deemphasize);
+    book.build()
+}
+
+fn main() {
+    if args_os().count() != 2 {
+        eprintln!("USAGE: {} <book>", args().next().expect("executable"));
+        return;
+    }
+    if let Err(e) = do_it(args_os().skip(1).next().expect("one argument")) {
+        eprintln!("{}", e);
+        process::exit(1);
+    }
+}
+
+impl Deemphasize {
+    fn remove_emphasis(num_removed_items: &mut i32, chapter: &mut Chapter) -> Result<String> {
+        let mut buf = String::with_capacity(chapter.content.len());
+        let events = Parser::new(&chapter.content).filter(|e| {
+            let should_keep = match *e {
+                Event::Start(Tag::Emphasis)
+                | Event::Start(Tag::Strong)
+                | Event::End(Tag::Emphasis)
+                | Event::End(Tag::Strong) => false,
+                _ => true,
+            };
+            if !should_keep {
+                *num_removed_items += 1;
+            }
+            should_keep
+        });
+        cmark(events, &mut buf, None)
+            .map(|_| buf)
+            .map_err(|err| Error::from(format!("Markdown serialization failed: {}", err)))
+    }
+}

src/bin/clean.rs

@@ -0,0 +1,30 @@
+use std::fs;
+use std::path::PathBuf;
+use clap::{App, ArgMatches, SubCommand};
+use mdbook::MDBook;
+use mdbook::errors::*;
+use get_book_dir;
+
+// Create clap subcommand arguments
+pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
+    SubCommand::with_name("clean")
+        .about("Delete built book")
+        .arg_from_usage(
+            "-d, --dest-dir=[dest-dir] 'The directory of built book{n}(Defaults to ./book when \
+             omitted)'",
+        )
+}
+
+// Clean command implementation
+pub fn execute(args: &ArgMatches) -> ::mdbook::errors::Result<()> {
+    let book_dir = get_book_dir(args);
+    let book = MDBook::load(&book_dir)?;
+
+    let dir_to_remove = match args.value_of("dest-dir") {
+        Some(dest_dir) => PathBuf::from(dest_dir),
+        None => book.root.join(&book.config.build.build_dir),
+    };
+    fs::remove_dir_all(&dir_to_remove).chain_err(|| "Unable to remove the build directory")?;
+
+    Ok(())
+}

src/bin/init.rs

@@ -1,8 +1,11 @@
 use std::io;
 use std::io::Write;
+use std::process::Command;
 use clap::{App, ArgMatches, SubCommand};
 use mdbook::MDBook;
 use mdbook::errors::Result;
+use mdbook::utils;
+use mdbook::config;
 use get_book_dir;
 
 // Create clap subcommand arguments
@@ -20,9 +23,11 @@ pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
 pub fn execute(args: &ArgMatches) -> Result<()> {
     let book_dir = get_book_dir(args);
     let mut builder = MDBook::init(&book_dir);
+    let mut config = config::Config::default();
 
     // If flag `--theme` is present, copy theme to src
     if args.is_present("theme") {
+        config.set("output.html.theme", "src/theme")?;
         // Skip this if `--force` is present
         if !args.is_present("force") {
             // Print warning
@@ -38,6 +43,8 @@ pub fn execute(args: &ArgMatches) -> Result<()> {
             if confirm() {
                 builder.copy_theme(true);
             }
+        } else {
+            builder.copy_theme(true);
         }
     }
 
@@ -47,13 +54,49 @@ pub fn execute(args: &ArgMatches) -> Result<()> {
         builder.create_gitignore(true);
     }
 
+    config.book.title = request_book_title();
+
+    if let Some(author) = get_author_name() {
+        debug!("Obtained user name from gitconfig: {:?}", author);
+        config.book.authors.push(author);
+        builder.with_config(config);
+    }
+
     builder.build()?;
     println!("\nAll done, no errors...");
 
     Ok(())
 }
 
-// Simple function that user comfirmation
+/// Obtains author name from git config file by running the `git config` command.
+fn get_author_name() -> Option<String> {
+    let output = Command::new("git")
+        .args(&["config", "--get", "user.name"])
+        .output()
+        .ok()?;
+
+    if output.status.success() {
+        Some(String::from_utf8_lossy(&output.stdout).trim().to_owned())
+    } else {
+        None
+    }
+}
+
+/// Request book title from user and return if provided.
+fn request_book_title() -> Option<String> {
+    println!("What title would you like to give the book? ");
+    io::stdout().flush().unwrap();
+    let mut resp = String::new();
+    io::stdin().read_line(&mut resp).unwrap();
+    let resp = resp.trim();
+    if resp.is_empty() {
+        None
+    } else {
+        Some(resp.into())
+    }
+}
+
+// Simple function for user confirmation
 fn confirm() -> bool {
     io::stdout().flush().unwrap();
     let mut s = String::new();

src/bin/mdbook.rs

@@ -1,6 +1,6 @@
+extern crate chrono;
 #[macro_use]
 extern crate clap;
-extern crate chrono;
 extern crate env_logger;
 extern crate error_chain;
 #[macro_use]
@@ -19,6 +19,7 @@ use env_logger::Builder;
 use mdbook::utils;
 
 pub mod build;
+pub mod clean;
 pub mod init;
 pub mod test;
 #[cfg(feature = "serve")]
@@ -37,14 +38,15 @@ fn main() {
                 .author("Mathieu David <mathieudavid@mathieudavid.org>")
                 // Get the version from our Cargo.toml using clap's crate_version!() macro
                 .version(concat!("v",crate_version!()))
-                .setting(AppSettings::SubcommandRequired)
+                .setting(AppSettings::ArgRequiredElseHelp)
                 .after_help("For more information about a specific command, \
                              try `mdbook <command> --help`\n\
                              Source code for mdbook available \
                              at: https://github.com/rust-lang-nursery/mdBook")
                 .subcommand(init::make_subcommand())
                 .subcommand(build::make_subcommand())
-                .subcommand(test::make_subcommand());
+                .subcommand(test::make_subcommand())
+                .subcommand(clean::make_subcommand());
 
     #[cfg(feature = "watch")]
     let app = app.subcommand(watch::make_subcommand());
@@ -55,6 +57,7 @@ fn main() {
     let res = match app.get_matches().subcommand() {
         ("init", Some(sub_matches)) => init::execute(sub_matches),
         ("build", Some(sub_matches)) => build::execute(sub_matches),
+        ("clean", Some(sub_matches)) => clean::execute(sub_matches),
         #[cfg(feature = "watch")]
         ("watch", Some(sub_matches)) => watch::execute(sub_matches),
         #[cfg(feature = "serve")]
@@ -74,11 +77,14 @@ fn init_logger() {
     let mut builder = Builder::new();
 
     builder.format(|formatter, record| {
-        writeln!(formatter, "{} [{}] ({}): {}",
-                 Local::now().format("%Y-%m-%d %H:%M:%S"),
-                 record.level(),
-                 record.target(),
-                 record.args())
+        writeln!(
+            formatter,
+            "{} [{}] ({}): {}",
+            Local::now().format("%Y-%m-%d %H:%M:%S"),
+            record.level(),
+            record.target(),
+            record.args()
+        )
     });
 
     if let Ok(var) = env::var("RUST_LOG") {
@@ -86,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();

src/book/book.rs

@@ -71,7 +71,8 @@ fn create_missing(src_dir: &Path, summary: &Summary) -> Result<()> {
 #[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
 pub struct Book {
     /// The sections in this book.
-    sections: Vec<BookItem>,
+    pub sections: Vec<BookItem>,
+    __non_exhaustive: (),
 }
 
 impl Book {
@@ -101,6 +102,12 @@ impl Book {
     {
         for_each_mut(&mut func, &mut self.sections);
     }
+
+    /// Append a `BookItem` to the `Book`.
+    pub fn push_item<I: Into<BookItem>>(&mut self, item: I) -> &mut Self {
+        self.sections.push(item.into());
+        self
+    }
 }
 
 pub fn for_each_mut<'a, F, I>(func: &mut F, items: I)
@@ -126,6 +133,12 @@ pub enum BookItem {
     Separator,
 }
 
+impl From<Chapter> for BookItem {
+    fn from(other: Chapter) -> BookItem {
+        BookItem::Chapter(other)
+    }
+}
+
 /// The representation of a "chapter", usually mapping to a single file on
 /// disk however it may contain multiple sub-chapters.
 #[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
@@ -140,15 +153,23 @@ pub struct Chapter {
     pub sub_items: Vec<BookItem>,
     /// The chapter's location, relative to the `SUMMARY.md` file.
     pub path: PathBuf,
+    /// An ordered list of the names of each chapter above this one, in the hierarchy.
+    pub parent_names: Vec<String>,
 }
 
 impl Chapter {
     /// Create a new chapter with the provided content.
-    pub fn new<P: Into<PathBuf>>(name: &str, content: String, path: P) -> Chapter {
+    pub fn new<P: Into<PathBuf>>(
+        name: &str,
+        content: String,
+        path: P,
+        parent_names: Vec<String>,
+    ) -> Chapter {
         Chapter {
             name: name.to_string(),
             content: content,
             path: path.into(),
+            parent_names: parent_names,
             ..Default::default()
         }
     }
@@ -171,21 +192,34 @@ fn load_book_from_disk<P: AsRef<Path>>(summary: &Summary, src_dir: P) -> Result<
     let mut chapters = Vec::new();
 
     for summary_item in summary_items {
-        let chapter = load_summary_item(summary_item, src_dir)?;
+        let chapter = load_summary_item(summary_item, src_dir, Vec::new())?;
         chapters.push(chapter);
     }
 
-    Ok(Book { sections: chapters })
+    Ok(Book {
+        sections: chapters,
+        __non_exhaustive: (),
+    })
 }
 
-fn load_summary_item<P: AsRef<Path>>(item: &SummaryItem, src_dir: P) -> Result<BookItem> {
+fn load_summary_item<P: AsRef<Path>>(
+    item: &SummaryItem,
+    src_dir: P,
+    parent_names: Vec<String>,
+) -> Result<BookItem> {
     match *item {
         SummaryItem::Separator => Ok(BookItem::Separator),
-        SummaryItem::Link(ref link) => load_chapter(link, src_dir).map(|c| BookItem::Chapter(c)),
+        SummaryItem::Link(ref link) => {
+            load_chapter(link, src_dir, parent_names).map(|c| BookItem::Chapter(c))
+        }
     }
 }
 
-fn load_chapter<P: AsRef<Path>>(link: &Link, src_dir: P) -> Result<Chapter> {
+fn load_chapter<P: AsRef<Path>>(
+    link: &Link,
+    src_dir: P,
+    parent_names: Vec<String>,
+) -> Result<Chapter> {
     debug!("Loading {} ({})", link.name, link.location.display());
     let src_dir = src_dir.as_ref();
 
@@ -206,12 +240,14 @@ fn load_chapter<P: AsRef<Path>>(link: &Link, src_dir: P) -> Result<Chapter> {
         .strip_prefix(&src_dir)
         .expect("Chapters are always inside a book");
 
-    let mut ch = Chapter::new(&link.name, content, stripped);
+    let mut sub_item_parents = parent_names.clone();
+    let mut ch = Chapter::new(&link.name, content, stripped, parent_names);
     ch.number = link.number.clone();
 
+    sub_item_parents.push(link.name.clone());
     let sub_items = link.nested_items
         .iter()
-        .map(|i| load_summary_item(i, src_dir))
+        .map(|i| load_summary_item(i, src_dir, sub_item_parents.clone()))
         .collect::<Result<Vec<_>>>()?;
 
     ch.sub_items = sub_items;
@@ -261,7 +297,7 @@ impl Display for Chapter {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use tempdir::TempDir;
+    use tempfile::{TempDir, Builder as TempFileBuilder};
     use std::io::Write;
 
     const DUMMY_SRC: &'static str = "
@@ -275,7 +311,7 @@ And here is some \
 
     /// Create a dummy `Link` in a temporary directory.
     fn dummy_link() -> (Link, TempDir) {
-        let temp = TempDir::new("book").unwrap();
+        let temp = TempFileBuilder::new().prefix("book").tempdir().unwrap();
 
         let chapter_path = temp.path().join("chapter_1.md");
         File::create(&chapter_path)
@@ -312,9 +348,14 @@ And here is some \
     #[test]
     fn load_a_single_chapter_from_disk() {
         let (link, temp_dir) = dummy_link();
-        let should_be = Chapter::new("Chapter 1", DUMMY_SRC.to_string(), "chapter_1.md");
+        let should_be = Chapter::new(
+            "Chapter 1",
+            DUMMY_SRC.to_string(),
+            "chapter_1.md",
+            Vec::new(),
+        );
 
-        let got = load_chapter(&link, temp_dir.path()).unwrap();
+        let got = load_chapter(&link, temp_dir.path(), Vec::new()).unwrap();
         assert_eq!(got, should_be);
     }
 
@@ -322,7 +363,7 @@ And here is some \
     fn cant_load_a_nonexistent_chapter() {
         let link = Link::new("Chapter 1", "/foo/bar/baz.md");
 
-        let got = load_chapter(&link, "");
+        let got = load_chapter(&link, "", Vec::new());
         assert!(got.is_err());
     }
 
@@ -335,6 +376,7 @@ And here is some \
             content: String::from("Hello World!"),
             number: Some(SectionNumber(vec![1, 2])),
             path: PathBuf::from("second.md"),
+            parent_names: vec![String::from("Chapter 1")],
             sub_items: Vec::new(),
         };
         let should_be = BookItem::Chapter(Chapter {
@@ -342,6 +384,7 @@ And here is some \
             content: String::from(DUMMY_SRC),
             number: None,
             path: PathBuf::from("chapter_1.md"),
+            parent_names: Vec::new(),
             sub_items: vec![
                 BookItem::Chapter(nested.clone()),
                 BookItem::Separator,
@@ -349,7 +392,7 @@ And here is some \
             ],
         });
 
-        let got = load_summary_item(&SummaryItem::Link(root), temp.path()).unwrap();
+        let got = load_summary_item(&SummaryItem::Link(root), temp.path(), Vec::new()).unwrap();
         assert_eq!(got, should_be);
     }
 
@@ -369,6 +412,7 @@ And here is some \
                     ..Default::default()
                 }),
             ],
+            ..Default::default()
         };
 
         let got = load_book_from_disk(&summary, temp.path()).unwrap();
@@ -387,6 +431,7 @@ And here is some \
                 }),
                 BookItem::Separator,
             ],
+            ..Default::default()
         };
 
         let should_be: Vec<_> = book.sections.iter().collect();
@@ -405,22 +450,26 @@ And here is some \
                     content: String::from(DUMMY_SRC),
                     number: None,
                     path: PathBuf::from("Chapter_1/index.md"),
+                    parent_names: Vec::new(),
                     sub_items: vec![
                         BookItem::Chapter(Chapter::new(
                             "Hello World",
                             String::new(),
                             "Chapter_1/hello.md",
+                            Vec::new(),
                         )),
                         BookItem::Separator,
                         BookItem::Chapter(Chapter::new(
                             "Goodbye World",
                             String::new(),
                             "Chapter_1/goodbye.md",
+                            Vec::new(),
                         )),
                     ],
                 }),
                 BookItem::Separator,
             ],
+            ..Default::default()
         };
 
         let got: Vec<_> = book.iter().collect();
@@ -452,22 +501,26 @@ And here is some \
                     content: String::from(DUMMY_SRC),
                     number: None,
                     path: PathBuf::from("Chapter_1/index.md"),
+                    parent_names: Vec::new(),
                     sub_items: vec![
                         BookItem::Chapter(Chapter::new(
                             "Hello World",
                             String::new(),
                             "Chapter_1/hello.md",
+                            Vec::new(),
                         )),
                         BookItem::Separator,
                         BookItem::Chapter(Chapter::new(
                             "Goodbye World",
                             String::new(),
                             "Chapter_1/goodbye.md",
+                            Vec::new(),
                         )),
                     ],
                 }),
                 BookItem::Separator,
             ],
+            ..Default::default()
         };
 
         let num_items = book.iter().count();

src/book/mod.rs

@@ -16,7 +16,7 @@ pub use self::init::BookBuilder;
 use std::path::PathBuf;
 use std::io::Write;
 use std::process::Command;
-use tempdir::TempDir;
+use tempfile::Builder as TempFileBuilder;
 use toml::Value;
 
 use utils;
@@ -213,7 +213,7 @@ impl MDBook {
             .flat_map(|x| vec![x.0, x.1])
             .collect();
 
-        let temp_dir = TempDir::new("mdbook")?;
+        let temp_dir = TempFileBuilder::new().prefix("mdbook").tempdir()?;
 
         let preprocess_context = PreprocessorContext::new(self.root.clone(), self.config.clone());
 
@@ -288,13 +288,12 @@ impl MDBook {
         self.root.join(&self.config.book.src)
     }
 
-    // FIXME: This really belongs as part of the `HtmlConfig`.
-    #[doc(hidden)]
+    /// Get the directory containing the theme resources for the book.
     pub fn theme_dir(&self) -> PathBuf {
-        match self.config.html_config().and_then(|h| h.theme) {
-            Some(d) => self.root.join(d),
-            None => self.root.join("theme"),
-        }
+        self.config
+            .html_config()
+            .unwrap_or_default()
+            .theme_dir(&self.root)
     }
 }
 

src/book/summary.rs

@@ -3,7 +3,7 @@ use std::iter::FromIterator;
 use std::ops::{Deref, DerefMut};
 use std::path::{Path, PathBuf};
 use memchr::{self, Memchr};
-use pulldown_cmark::{self, Alignment, Event, Tag};
+use pulldown_cmark::{self, Event, Tag};
 use errors::*;
 
 /// Parse the text from a `SUMMARY.md` file into a sort of "recipe" to be
@@ -313,24 +313,15 @@ impl<'a> SummaryParser<'a> {
                     break;
                 }
                 Some(Event::Start(other_tag)) => {
-                    // FIXME: Remove this when google/pulldown_cmark#120 lands (new patch release)
-                    // replace with `other_tag == Tag::Rule`
-                    if tag_eq(&other_tag, &Tag::Rule) {
+                    if other_tag == Tag::Rule {
                         items.push(SummaryItem::Separator);
                     }
                     trace!("Skipping contents of {:?}", other_tag);
 
                     // Skip over the contents of this tag
                     while let Some(event) = self.next_event() {
-                        // FIXME: Remove this when google/pulldown_cmark#120 lands (new patch release)
-                        // and replace the nested if-let with:
-                        // if next == Event::End(other_tag.clone()) {
-                        //     break;
-                        // }
-                        if let Event::End(tag) = event {
-                            if tag_eq(&tag, &other_tag) {
-                                break;
-                            }
+                        if event == Event::End(other_tag.clone()) {
+                            break;
                         }
                     }
 
@@ -484,43 +475,6 @@ fn stringify_events(events: Vec<Event>) -> String {
         .collect()
 }
 
-// FIXME: Remove this when google/pulldown_cmark#120 lands (new patch release)
-fn tag_eq(left: &Tag, right: &Tag) -> bool {
-    match (left, right) {
-        (&Tag::Paragraph, &Tag::Paragraph) => true,
-        (&Tag::Rule, &Tag::Rule) => true,
-        (&Tag::Header(a), &Tag::Header(b)) => a == b,
-        (&Tag::BlockQuote, &Tag::BlockQuote) => true,
-        (&Tag::CodeBlock(ref a), &Tag::CodeBlock(ref b)) => a == b,
-        (&Tag::List(ref a), &Tag::List(ref b)) => a == b,
-        (&Tag::Item, &Tag::Item) => true,
-        (&Tag::FootnoteDefinition(ref a), &Tag::FootnoteDefinition(ref b)) => a == b,
-        (&Tag::Table(ref a), &Tag::Table(ref b)) => {
-            a.iter().zip(b.iter()).all(|(l, r)| alignment_eq(*l, *r))
-        }
-        (&Tag::TableHead, &Tag::TableHead) => true,
-        (&Tag::TableRow, &Tag::TableRow) => true,
-        (&Tag::TableCell, &Tag::TableCell) => true,
-        (&Tag::Emphasis, &Tag::Emphasis) => true,
-        (&Tag::Strong, &Tag::Strong) => true,
-        (&Tag::Code, &Tag::Code) => true,
-        (&Tag::Link(ref a_1, ref a_2), &Tag::Link(ref b_1, ref b_2)) => a_1 == b_1 && a_2 == b_2,
-        (&Tag::Image(ref a_1, ref a_2), &Tag::Image(ref b_1, ref b_2)) => a_1 == b_1 && a_2 == b_2,
-        _ => false,
-    }
-}
-
-// FIXME: Remove this when google/pulldown_cmark#120 lands (new patch release)
-fn alignment_eq(left: Alignment, right: Alignment) -> bool {
-    match (left, right) {
-        (Alignment::None, Alignment::None) => true,
-        (Alignment::Left, Alignment::Left) => true,
-        (Alignment::Center, Alignment::Center) => true,
-        (Alignment::Right, Alignment::Right) => true,
-        _ => false,
-    }
-}
-
 /// A section number like "1.2.3", basically just a newtype'd `Vec<u32>` with
 /// a pretty `Display` impl.
 #[derive(Debug, PartialEq, Clone, Default, Serialize, Deserialize)]

src/config.rs

@@ -1,13 +1,13 @@
 //! Mdbook's configuration system.
-//! 
+//!
 //! The main entrypoint of the `config` module is the `Config` struct. This acts
 //! essentially as a bag of configuration information, with a couple
-//! pre-determined tables (`BookConfig` and `BuildConfig`) as well as support 
+//! pre-determined tables (`BookConfig` and `BuildConfig`) as well as support
 //! for arbitrary data which is exposed to plugins and alternate backends.
-//! 
-//! 
+//!
+//!
 //! # Examples
-//! 
+//!
 //! ```rust
 //! # extern crate mdbook;
 //! # use mdbook::errors::*;
@@ -15,31 +15,31 @@
 //! use std::path::PathBuf;
 //! use mdbook::Config;
 //! use toml::Value;
-//! 
+//!
 //! # fn run() -> Result<()> {
 //! let src = r#"
 //! [book]
 //! title = "My Book"
 //! authors = ["Michael-F-Bryan"]
-//! 
+//!
 //! [build]
 //! src = "out"
-//! 
+//!
 //! [other-table.foo]
 //! bar = 123
 //! "#;
-//! 
+//!
 //! // load the `Config` from a toml string
 //! let mut cfg = Config::from_str(src)?;
-//! 
+//!
 //! // retrieve a nested value
 //! let bar = cfg.get("other-table.foo.bar").cloned();
 //! assert_eq!(bar, Some(Value::Integer(123)));
-//! 
+//!
 //! // Set the `output.html.theme` directory
 //! assert!(cfg.get("output.html").is_none());
 //! cfg.set("output.html.theme", "./themes");
-//! 
+//!
 //! // then load it again, automatically deserializing to a `PathBuf`.
 //! let got: PathBuf = cfg.get_deserialized("output.html.theme")?;
 //! assert_eq!(got, PathBuf::from("./themes"));
@@ -383,7 +383,6 @@ pub struct BuildConfig {
     pub create_missing: bool,
     /// Which preprocessors should be applied
     pub preprocess: Option<Vec<String>>,
-
 }
 
 impl Default for BuildConfig {
@@ -410,7 +409,7 @@ pub struct HtmlConfig {
     pub google_analytics: Option<String>,
     /// Additional CSS stylesheets to include in the rendered page's `<head>`.
     pub additional_css: Vec<PathBuf>,
-    /// Additional JS scripts to include at the bottom of the rendered page's 
+    /// Additional JS scripts to include at the bottom of the rendered page's
     /// `<body>`.
     pub additional_js: Vec<PathBuf>,
     /// Playpen settings.
@@ -425,25 +424,85 @@ pub struct HtmlConfig {
     pub livereload_url: Option<String>,
     /// Should section labels be rendered?
     pub no_section_label: bool,
+    /// Search settings. If `None`, the default will be used.
+    pub search: Option<Search>,
+}
+
+impl HtmlConfig {
+    /// Returns the directory of theme from the provided root directory. If the
+    /// directory is not present it will append the default directory of "theme"
+    pub fn theme_dir(&self, root: &PathBuf) -> PathBuf {
+        match self.theme {
+            Some(ref d) => root.join(d),
+            None => root.join("theme"),
+        }
+    }
 }
 
 /// Configuration for tweaking how the the HTML renderer handles the playpen.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(default, rename_all = "kebab-case")]
 pub struct Playpen {
-    /// The path to the editor to use. Defaults to the [Ace Editor].
-    /// 
-    /// [Ace Editor]: https://ace.c9.io/
-    pub editor: PathBuf,
-    /// Should playpen snippets be editable? Defaults to `false`.
+    /// Should playpen snippets be editable? Default: `false`.
     pub editable: bool,
+    /// Copy JavaScript files for the editor to the output directory?
+    /// Default: `true`.
+    pub copy_js: bool,
 }
 
 impl Default for Playpen {
     fn default() -> Playpen {
         Playpen {
-            editor: PathBuf::from("ace"),
             editable: false,
+            copy_js: true,
+        }
+    }
+}
+
+/// Configuration of the search functionality of the HTML renderer.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(default, rename_all = "kebab-case")]
+pub struct Search {
+    /// Maximum number of visible results. Default: `30`.
+    pub limit_results: u32,
+    /// The number of words used for a search result teaser. Default: `30`,
+    pub teaser_word_count: u32,
+    /// Define the logical link between multiple search words.
+    /// If true, all search words must appear in each result. Default: `true`.
+    pub use_boolean_and: bool,
+    /// Boost factor for the search result score if a search word appears in the header.
+    /// Default: `2`.
+    pub boost_title: u8,
+    /// 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.
+    /// Default: `1`.
+    pub boost_hierarchy: u8,
+    /// Boost factor for the search result score if a search word appears in the text.
+    /// Default: `1`.
+    pub boost_paragraph: u8,
+    /// True if the searchword `micro` should match `microwave`. Default: `true`.
+    pub expand: bool,
+    /// Documents are split into smaller parts, seperated by headings. This defines, until which
+    /// level of heading documents should be split. Default: `3`. (`### This is a level 3 heading`)
+    pub heading_split_level: u8,
+    /// Copy JavaScript files for the search functionality to the output directory?
+    /// Default: `true`.
+    pub copy_js: bool,
+}
+
+impl Default for Search {
+    fn default() -> Search {
+        // Please update the documentation of `Search` when changing values!
+        Search {
+            limit_results: 30,
+            teaser_word_count: 30,
+            use_boolean_and: false,
+            boost_title: 2,
+            boost_hierarchy: 1,
+            boost_paragraph: 1,
+            expand: true,
+            heading_split_level: 3,
+            copy_js: true,
         }
     }
 }
@@ -520,12 +579,14 @@ mod tests {
         let build_should_be = BuildConfig {
             build_dir: PathBuf::from("outputs"),
             create_missing: false,
-            preprocess: Some(vec!["first_preprocessor".to_string(),
-                                  "second_preprocessor".to_string()]),
+            preprocess: Some(vec![
+                "first_preprocessor".to_string(),
+                "second_preprocessor".to_string(),
+            ]),
         };
         let playpen_should_be = Playpen {
             editable: true,
-            editor: PathBuf::from("ace"),
+            copy_js: true,
         };
         let html_should_be = HtmlConfig {
             curly_quotes: true,

src/lib.rs

@@ -1,7 +1,8 @@
 //! # mdBook
 //!
-//! **mdBook** is similar to GitBook but implemented in Rust.
-//! It offers a command line interface, but can also be used as a regular crate.
+//! **mdBook** is a tool for rendering a collection of markdown documents into
+//! a form more suitable for end users like HTML or EPUB.  It offers a command
+//! line interface, but this crate can be used if more control is required.
 //!
 //! This is the API doc, the [user guide] is also available if you want
 //! information about the command line tool, format, structure etc. It is also
@@ -15,6 +16,12 @@
 //! - Accessing the public API to help create a new Renderer
 //! - ...
 //!
+//! > **Note:** While we try to ensure `mdbook`'s command-line interface and
+//! > behaviour are backwards compatible, the tool's internals are still
+//! > evolving and being iterated on. If you wish to prevent accidental
+//! > breakages it is recommended to pin any tools building on top of the
+//! > `mdbook` crate to a specific release.
+//!
 //! # Examples
 //!
 //! If creating a new book from scratch, you'll want to get a `BookBuilder` via
@@ -52,20 +59,20 @@
 //!
 //! ## Implementing a new Backend
 //!
-//! `mdbook` has a fairly flexible mechanism for creating additional backends 
+//! `mdbook` has a fairly flexible mechanism for creating additional backends
 //! for your book. The general idea is you'll add an extra table in the book's
 //! `book.toml` which specifies an executable to be invoked by `mdbook`. This
-//! executable will then be called during a build, with an in-memory 
+//! executable will then be called during a build, with an in-memory
 //! representation ([`RenderContext`]) of the book being passed to the
-//! subprocess via `stdin`. 
-//! 
-//! The [`RenderContext`] gives the backend access to the contents of 
+//! subprocess via `stdin`.
+//!
+//! The [`RenderContext`] gives the backend access to the contents of
 //! `book.toml` and lets it know which directory all generated artefacts should
 //! be placed in. For a much more in-depth explanation, consult the [relevant
 //! chapter] in the *For Developers* section of the user guide.
-//! 
-//! To make creating a backend easier, the `mdbook` crate can be imported 
-//! directly, making deserializing the `RenderContext` easy and giving you 
+//!
+//! To make creating a backend easier, the `mdbook` crate can be imported
+//! directly, making deserializing the `RenderContext` easy and giving you
 //! access to the various methods for working with the [`Config`].
 //!
 //! [user guide]: https://rust-lang-nursery.github.io/mdBook/
@@ -92,7 +99,7 @@ extern crate serde_derive;
 #[macro_use]
 extern crate serde_json;
 extern crate shlex;
-extern crate tempdir;
+extern crate tempfile;
 extern crate toml;
 extern crate toml_query;
 
@@ -122,6 +129,7 @@ pub mod errors {
             HandlebarsRender(::handlebars::RenderError) #[doc = "Handlebars rendering failed"];
             HandlebarsTemplate(Box<::handlebars::TemplateError>) #[doc = "Unable to parse the template"];
             Utf8(::std::string::FromUtf8Error) #[doc = "Invalid UTF-8"];
+            SerdeJson(::serde_json::Error) #[doc = "JSON conversion failed"];
         }
 
         links {

src/preprocess/links.rs

@@ -10,7 +10,7 @@ use book::{Book, BookItem};
 
 const ESCAPE_CHAR: char = '\\';
 
-/// A preprocessor for expanding the `{{# playpen}}` and `{{# include}}` 
+/// A preprocessor for expanding the `{{# playpen}}` and `{{# include}}`
 /// helpers in a chapter.
 pub struct LinkPreprocessor;
 
@@ -87,8 +87,14 @@ enum LinkType<'a> {
 fn parse_include_path(path: &str) -> LinkType<'static> {
     let mut parts = path.split(':');
     let path = parts.next().unwrap().into();
-    let start = parts.next().and_then(|s| s.parse::<usize>().ok());
-    let end = parts.next().and_then(|s| s.parse::<usize>().ok());
+    // subtract 1 since line numbers usually begin with 1
+    let start = parts
+        .next()
+        .and_then(|s| s.parse::<usize>().ok())
+        .map(|val| val.checked_sub(1).unwrap_or(0));
+    let end = parts.next();
+    let has_end = end.is_some();
+    let end = end.and_then(|s| s.parse::<usize>().ok());
     match start {
         Some(start) => match end {
             Some(end) => LinkType::IncludeRange(
@@ -98,7 +104,17 @@ fn parse_include_path(path: &str) -> LinkType<'static> {
                     end: end,
                 },
             ),
-            None => LinkType::IncludeRangeFrom(path, RangeFrom { start: start }),
+            None => if has_end {
+                LinkType::IncludeRangeFrom(path, RangeFrom { start: start })
+            } else {
+                LinkType::IncludeRange(
+                    path,
+                    Range {
+                        start: start,
+                        end: start + 1,
+                    },
+                )
+            },
         },
         None => match end {
             Some(end) => LinkType::IncludeRangeTo(path, RangeTo { end: end }),
@@ -276,13 +292,31 @@ mod tests {
                 Link {
                     start_index: 22,
                     end_index: 48,
-                    link: LinkType::IncludeRange(PathBuf::from("file.rs"), 10..20),
+                    link: LinkType::IncludeRange(PathBuf::from("file.rs"), 9..20),
                     link_text: "{{#include file.rs:10:20}}",
                 },
             ]
         );
     }
 
+    #[test]
+    fn test_find_links_with_line_number() {
+        let s = "Some random text with {{#include file.rs:10}}...";
+        let res = find_links(s).collect::<Vec<_>>();
+        println!("\nOUTPUT: {:?}\n", res);
+        assert_eq!(
+            res,
+            vec![
+                Link {
+                    start_index: 22,
+                    end_index: 45,
+                    link: LinkType::IncludeRange(PathBuf::from("file.rs"), 9..10),
+                    link_text: "{{#include file.rs:10}}",
+                },
+            ]
+        );
+    }
+
     #[test]
     fn test_find_links_with_from_range() {
         let s = "Some random text with {{#include file.rs:10:}}...";
@@ -294,7 +328,7 @@ mod tests {
                 Link {
                     start_index: 22,
                     end_index: 46,
-                    link: LinkType::IncludeRangeFrom(PathBuf::from("file.rs"), 10..),
+                    link: LinkType::IncludeRangeFrom(PathBuf::from("file.rs"), 9..),
                     link_text: "{{#include file.rs:10:}}",
                 },
             ]

src/renderer/html_handlebars/hbs_renderer.rs

@@ -1,21 +1,19 @@
-use renderer::html_handlebars::helpers;
-use renderer::{RenderContext, Renderer};
 use book::{Book, BookItem, Chapter};
 use config::{Config, HtmlConfig, Playpen};
-use {theme, utils};
-use theme::{playpen_editor, Theme};
 use errors::*;
-use regex::{Captures, Regex};
+use renderer::{RenderContext, Renderer};
+use renderer::html_handlebars::helpers;
+use theme::{self, Theme, playpen_editor};
+use utils;
 
-#[allow(unused_imports)] use std::ascii::AsciiExt;
-use std::path::{Path, PathBuf};
-use std::fs::{self, File};
-use std::io::{Read, Write};
 use std::collections::BTreeMap;
 use std::collections::HashMap;
+use std::fs::{self, File};
+use std::io::Read;
+use std::path::{Path, PathBuf};
 
 use handlebars::Handlebars;
-
+use regex::{Captures, Regex};
 use serde_json;
 
 #[derive(Default)]
@@ -26,23 +24,10 @@ impl HtmlHandlebars {
         HtmlHandlebars
     }
 
-    fn write_file<P: AsRef<Path>>(
-        &self,
-        build_dir: &Path,
-        filename: P,
-        content: &[u8],
-    ) -> Result<()> {
-        let path = build_dir.join(filename);
-
-        utils::fs::create_file(&path)?
-            .write_all(content)
-            .map_err(|e| e.into())
-    }
-
     fn render_item(
         &self,
-                   item: &BookItem,
-                   mut ctx: RenderItemContext,
+        item: &BookItem,
+        mut ctx: RenderItemContext,
         print_content: &mut String,
     ) -> Result<()> {
         // FIXME: This should be made DRY-er and rely less on mutable state
@@ -56,6 +41,11 @@ impl HtmlHandlebars {
                 let path = ch.path
                     .to_str()
                     .chain_err(|| "Could not convert path to str")?;
+                let filepath = Path::new(&ch.path)
+                    .with_extension("html");
+                let filepathstr = filepath.to_str()
+                    .chain_err(|| "Could not convert HTML path to str")?;
+                let filepathstr = utils::fs::normalize_path(filepathstr);
 
                 // "print.html" is used for the print page.
                 if ch.path == Path::new("print.md") {
@@ -83,18 +73,15 @@ impl HtmlHandlebars {
                 debug!("Render template");
                 let rendered = ctx.handlebars.render("index", &ctx.data)?;
 
-                let filepath = Path::new(&ch.path).with_extension("html");
                 let rendered = self.post_process(
                     rendered,
-                    &normalize_path(filepath.to_str().ok_or_else(|| {
-                        Error::from(format!("Bad file name: {}", filepath.display()))
-                    })?),
+                    &filepathstr,
                     &ctx.html_config.playpen,
                 );
 
                 // Write to file
-                debug!("Creating {} ✓", filepath.display());
-                self.write_file(&ctx.destination, filepath, &rendered.into_bytes())?;
+                debug!("Creating {} ✓", filepathstr);
+                utils::fs::write_file(&ctx.destination, &filepath, &rendered.into_bytes())?;
 
                 if ctx.is_index {
                     self.render_index(ch, &ctx.destination)?;
@@ -123,7 +110,7 @@ impl HtmlHandlebars {
                          .collect::<Vec<&str>>()
                          .join("\n");
 
-        self.write_file(destination, "index.html", content.as_bytes())?;
+        utils::fs::write_file(destination, "index.html", content.as_bytes())?;
 
         debug!(
             "Creating index.html from {} ✓",
@@ -153,45 +140,47 @@ impl HtmlHandlebars {
         theme: &Theme,
         html_config: &HtmlConfig,
     ) -> Result<()> {
-        self.write_file(destination, "book.js", &theme.js)?;
-        self.write_file(destination, "book.css", &theme.css)?;
-        self.write_file(destination, "favicon.png", &theme.favicon)?;
-        self.write_file(destination, "highlight.css", &theme.highlight_css)?;
-        self.write_file(destination, "tomorrow-night.css", &theme.tomorrow_night_css)?;
-        self.write_file(destination, "ayu-highlight.css", &theme.ayu_highlight_css)?;
-        self.write_file(destination, "highlight.js", &theme.highlight_js)?;
-        self.write_file(destination, "clipboard.min.js", &theme.clipboard_js)?;
-        self.write_file(
+        use utils::fs::write_file;
+
+        write_file(destination, "book.js", &theme.js)?;
+        write_file(destination, "book.css", &theme.css)?;
+        write_file(destination, "favicon.png", &theme.favicon)?;
+        write_file(destination, "highlight.css", &theme.highlight_css)?;
+        write_file(destination, "tomorrow-night.css", &theme.tomorrow_night_css)?;
+        write_file(destination, "ayu-highlight.css", &theme.ayu_highlight_css)?;
+        write_file(destination, "highlight.js", &theme.highlight_js)?;
+        write_file(destination, "clipboard.min.js", &theme.clipboard_js)?;
+        write_file(
             destination,
             "_FontAwesome/css/font-awesome.css",
             theme::FONT_AWESOME,
         )?;
-        self.write_file(
+        write_file(
             destination,
             "_FontAwesome/fonts/fontawesome-webfont.eot",
             theme::FONT_AWESOME_EOT,
         )?;
-        self.write_file(
+        write_file(
             destination,
             "_FontAwesome/fonts/fontawesome-webfont.svg",
             theme::FONT_AWESOME_SVG,
         )?;
-        self.write_file(
+        write_file(
             destination,
             "_FontAwesome/fonts/fontawesome-webfont.ttf",
             theme::FONT_AWESOME_TTF,
         )?;
-        self.write_file(
+        write_file(
             destination,
             "_FontAwesome/fonts/fontawesome-webfont.woff",
             theme::FONT_AWESOME_WOFF,
         )?;
-        self.write_file(
+        write_file(
             destination,
             "_FontAwesome/fonts/fontawesome-webfont.woff2",
             theme::FONT_AWESOME_WOFF2,
         )?;
-        self.write_file(
+        write_file(
             destination,
             "_FontAwesome/fonts/FontAwesome.ttf",
             theme::FONT_AWESOME_TTF,
@@ -200,16 +189,15 @@ impl HtmlHandlebars {
         let playpen_config = &html_config.playpen;
 
         // Ace is a very large dependency, so only load it when requested
-        if playpen_config.editable {
+        if playpen_config.editable && playpen_config.copy_js {
             // Load the editor
-            let editor = playpen_editor::PlaypenEditor::new(&playpen_config.editor);
-            self.write_file(destination, "editor.js", &editor.js)?;
-            self.write_file(destination, "ace.js", &editor.ace_js)?;
-            self.write_file(destination, "mode-rust.js", &editor.mode_rust_js)?;
-            self.write_file(destination, "theme-dawn.js", &editor.theme_dawn_js)?;
-            self.write_file(destination,
+            write_file(destination, "editor.js", playpen_editor::JS)?;
+            write_file(destination, "ace.js", playpen_editor::ACE_JS)?;
+            write_file(destination, "mode-rust.js", playpen_editor::MODE_RUST_JS)?;
+            write_file(destination, "theme-dawn.js", playpen_editor::THEME_DAWN_JS)?;
+            write_file(destination,
                 "theme-tomorrow_night.js",
-                &editor.theme_tomorrow_night_js,
+                playpen_editor::THEME_TOMORROW_NIGHT_JS,
             )?;
         }
 
@@ -238,23 +226,28 @@ impl HtmlHandlebars {
 
     /// Copy across any additional CSS and JavaScript files which the book
     /// has been configured to use.
-    fn copy_additional_css_and_js(&self, html: &HtmlConfig, destination: &Path) -> Result<()> {
+    fn copy_additional_css_and_js(&self, html: &HtmlConfig, root: &Path, destination: &Path) -> Result<()> {
         let custom_files = html.additional_css.iter().chain(html.additional_js.iter());
 
         debug!("Copying additional CSS and JS");
 
         for custom_file in custom_files {
+            let input_location = root.join(custom_file);
             let output_location = destination.join(custom_file);
+            if let Some(parent) = output_location.parent() {
+                fs::create_dir_all(parent)
+                    .chain_err(|| format!("Unable to create {}", parent.display()))?;
+            }
             debug!(
                 "Copying {} -> {}",
-                custom_file.display(),
+                input_location.display(),
                 output_location.display()
             );
 
-            fs::copy(custom_file, &output_location).chain_err(|| {
+            fs::copy(&input_location, &output_location).chain_err(|| {
                 format!(
                     "Unable to copy {} to {}",
-                    custom_file.display(),
+                    input_location.display(),
                     output_location.display()
                 )
             })?;
@@ -302,15 +295,19 @@ impl Renderer for HtmlHandlebars {
         fs::create_dir_all(&destination)
             .chain_err(|| "Unexpected error when constructing destination path")?;
 
-        for (i, item) in book.iter().enumerate() {
+        let mut is_index = true;
+        for item in book.iter() {
             let ctx = RenderItemContext {
                 handlebars: &handlebars,
                 destination: destination.to_path_buf(),
                 data: data.clone(),
-                is_index: i == 0,
+                is_index: is_index,
                 html_config: html_config.clone(),
             };
-            self.render_item(item, ctx, &mut print_content)?;
+            self.render_item(item,
+                             ctx,
+                             &mut print_content)?;
+            is_index = false;
         }
 
         // Print version
@@ -321,22 +318,25 @@ impl Renderer for HtmlHandlebars {
 
         // Render the handlebars template with the data
         debug!("Render template");
-
         let rendered = handlebars.render("index", &data)?;
 
         let rendered = self.post_process(rendered,
                                          "print.html",
                                          &html_config.playpen);
 
-        self.write_file(&destination, "print.html", &rendered.into_bytes())?;
+        utils::fs::write_file(&destination, "print.html", &rendered.into_bytes())?;
         debug!("Creating print.html ✓");
 
         debug!("Copy static files");
         self.copy_static_files(&destination, &theme, &html_config)
             .chain_err(|| "Unable to copy across static files")?;
-        self.copy_additional_css_and_js(&html_config, &destination)
+        self.copy_additional_css_and_js(&html_config, &ctx.root, &destination)
             .chain_err(|| "Unable to copy across additional CSS and JS")?;
 
+        // Render search index
+        #[cfg(feature = "search")]
+        super::search::create_files(&html_config.search.unwrap_or_default(), &destination, &book)?;
+
         // Copy all remaining files
         utils::fs::copy_files_except_ext(&src_dir, &destination, true, &["md"])?;
 
@@ -371,11 +371,11 @@ fn make_data(root: &Path, book: &Book, config: &Config, html_config: &HtmlConfig
         let mut css = Vec::new();
         for style in &html.additional_css {
             match style.strip_prefix(root) {
-                Ok(p) => css.push(p.to_str().expect("Could not convert to str")),
+                Ok(p) => {
+                    css.push(p.to_str().expect("Could not convert to str"))
+                },
                 Err(_) => {
-                    css.push(style.file_name()
-                                  .expect("File has a file name")
-                                  .to_str()
+                    css.push(style.to_str()
                                   .expect("Could not convert to str"))
                 }
             }
@@ -400,16 +400,22 @@ fn make_data(root: &Path, book: &Book, config: &Config, html_config: &HtmlConfig
         data.insert("additional_js".to_owned(), json!(js));
     }
 
-    if html.playpen.editable {
-        data.insert("playpens_editable".to_owned(), json!(true));
-        data.insert("editor_js".to_owned(), json!("editor.js"));
-        data.insert("ace_js".to_owned(), json!("ace.js"));
-        data.insert("mode_rust_js".to_owned(), json!("mode-rust.js"));
-        data.insert("theme_dawn_js".to_owned(), json!("theme-dawn.js"));
-        data.insert("theme_tomorrow_night_js".to_owned(),
-                    json!("theme-tomorrow_night.js"));
+    if html.playpen.editable && html.playpen.copy_js {
+        data.insert("playpen_js".to_owned(), json!(true));
     }
 
+    let search = html_config.search.clone();
+    if cfg!(feature = "search") {
+        data.insert("search_enabled".to_owned(), json!(true));
+        if search.unwrap_or_default().copy_js {
+            data.insert("search_js".to_owned(), json!(true));
+        }
+    } else if search.is_some() {
+        warn!("mdBook compiled without search support, ignoring `output.html.search` table");
+        warn!("please reinstall with `cargo install mdbook --force --features search`\
+            to use the search feature")
+    }
+    
     let mut chapters = vec![];
 
     for item in book.iter() {
@@ -464,7 +470,7 @@ fn wrap_header_with_link(level: usize,
                          id_counter: &mut HashMap<String, usize>,
                          filepath: &str)
                          -> String {
-    let raw_id = id_from_content(content);
+    let raw_id = utils::id_from_content(content);
 
     let id_count = id_counter.entry(raw_id.clone()).or_insert(0);
 
@@ -484,33 +490,6 @@ fn wrap_header_with_link(level: usize,
     )
 }
 
-/// Generate an id for use with anchors which is derived from a "normalised"
-/// string.
-fn id_from_content(content: &str) -> String {
-    let mut content = content.to_string();
-
-    // Skip any tags or html-encoded stuff
-    const REPL_SUB: &[&str] = &["<em>",
-                                "</em>",
-                                "<code>",
-                                "</code>",
-                                "<strong>",
-                                "</strong>",
-                                "&lt;",
-                                "&gt;",
-                                "&amp;",
-                                "&#39;",
-                                "&quot;"];
-    for sub in REPL_SUB {
-        content = content.replace(sub, "");
-    }
-
-    // Remove spaces and hastags indicating a header
-    let trimmed = content.trim().trim_left_matches('#').trim();
-
-    normalize_id(trimmed)
-}
-
 // anchors to the same page (href="#anchor") do not work because of
 // <base href="../"> pointing to the root folder. This function *fixes*
 // that in a very inelegant way
@@ -550,8 +529,7 @@ fn fix_code_blocks(html: &str) -> String {
                 before = before,
                 classes = classes,
                 after = after)
-    })
-         .into_owned()
+    }).into_owned()
 }
 
 fn add_playpen_pre(html: &str, playpen_config: &Playpen) -> String {
@@ -586,8 +564,7 @@ fn add_playpen_pre(html: &str, playpen_config: &Playpen) -> String {
             // not language-rust, so no-op
             text.to_owned()
         }
-    })
-         .into_owned()
+    }).into_owned()
 }
 
 fn partition_source(s: &str) -> (String, String) {
@@ -619,26 +596,6 @@ struct RenderItemContext<'a> {
     html_config: HtmlConfig,
 }
 
-pub fn normalize_path(path: &str) -> String {
-    use std::path::is_separator;
-    path.chars()
-        .map(|ch| if is_separator(ch) { '/' } else { ch })
-        .collect::<String>()
-}
-
-pub fn normalize_id(content: &str) -> String {
-    content.chars()
-           .filter_map(|ch| if ch.is_alphanumeric() || ch == '_' || ch == '-' {
-                           Some(ch.to_ascii_lowercase())
-                       } else if ch.is_whitespace() {
-                           Some('-')
-                       } else {
-                           None
-                       })
-           .collect::<String>()
-}
-
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -682,12 +639,4 @@ mod tests {
             assert_eq!(got, should_be);
         }
     }
-
-    #[test]
-    fn anchor_generation() {
-        assert_eq!(id_from_content("## `--passes`: add more rustdoc passes"),
-                   "--passes-add-more-rustdoc-passes");
-        assert_eq!(id_from_content("## Method-call expressions"),
-                   "method-call-expressions");
-    }
 }

src/renderer/html_handlebars/helpers/mod.rs

@@ -1,2 +1,2 @@
-pub mod navigation;
 pub mod toc;
+pub mod navigation;

src/renderer/html_handlebars/helpers/navigation.rs

@@ -4,7 +4,6 @@ use std::collections::BTreeMap;
 use serde_json;
 use handlebars::{Context, Handlebars, Helper, RenderContext, RenderError, Renderable};
 
-
 type StringMap = BTreeMap<String, String>;
 
 /// Target for `find_chapter`.
@@ -15,22 +14,23 @@ enum Target {
 
 impl Target {
     /// Returns target if found.
-    fn find(&self,
-            base_path: &String,
-            current_path: &String,
-            current_item: &StringMap,
-            previous_item: &StringMap,
-            ) -> Result<Option<StringMap>, RenderError> {
+    fn find(
+        &self,
+        base_path: &String,
+        current_path: &String,
+        current_item: &StringMap,
+        previous_item: &StringMap,
+    ) -> Result<Option<StringMap>, RenderError> {
         match self {
             &Target::Next => {
-                let previous_path = previous_item.get("path").ok_or_else(|| {
-                    RenderError::new("No path found for chapter in JSON data")
-                })?;
+                let previous_path = previous_item
+                    .get("path")
+                    .ok_or_else(|| RenderError::new("No path found for chapter in JSON data"))?;
 
                 if previous_path == base_path {
                     return Ok(Some(current_item.clone()));
                 }
-            },
+            }
 
             &Target::Previous => {
                 if current_path == base_path {
@@ -43,21 +43,18 @@ impl Target {
     }
 }
 
-fn find_chapter(
-    rc: &mut RenderContext,
-    target: Target
-) -> Result<Option<StringMap>, RenderError> {
+fn find_chapter(rc: &mut RenderContext, target: Target) -> Result<Option<StringMap>, RenderError> {
     debug!("Get data from context");
 
-    let chapters = rc.evaluate_absolute("chapters").and_then(|c| {
+    let chapters = rc.evaluate_absolute("chapters", true).and_then(|c| {
         serde_json::value::from_value::<Vec<StringMap>>(c.clone())
             .map_err(|_| RenderError::new("Could not decode the JSON data"))
     })?;
 
-    let base_path = rc.evaluate_absolute("path")?
-                      .as_str()
-                      .ok_or_else(|| RenderError::new("Type error for `path`, string expected"))?
-                      .replace("\"", "");
+    let base_path = rc.evaluate_absolute("path", true)?
+        .as_str()
+        .ok_or_else(|| RenderError::new("Type error for `path`, string expected"))?
+        .replace("\"", "");
 
     let mut previous: Option<StringMap> = None;
 
@@ -78,7 +75,7 @@ fn find_chapter(
         }
     }
 
-   Ok(None)
+    Ok(None)
 }
 
 fn render(
@@ -91,18 +88,21 @@ fn render(
 
     let mut context = BTreeMap::new();
 
-    chapter.get("name")
-            .ok_or_else(|| RenderError::new("No title found for chapter in JSON data"))
-            .map(|name| context.insert("title".to_owned(), json!(name)))?;
+    chapter
+        .get("name")
+        .ok_or_else(|| RenderError::new("No title found for chapter in JSON data"))
+        .map(|name| context.insert("title".to_owned(), json!(name)))?;
 
-    chapter.get("path")
-            .ok_or_else(|| RenderError::new("No path found for chapter in JSON data"))
-            .and_then(|p| {
-                    Path::new(p).with_extension("html")
-                    .to_str()
-                    .ok_or_else(|| RenderError::new("Link could not be converted to str"))
-                    .map(|p| context.insert("link".to_owned(), json!(p.replace("\\", "/"))))
-            })?;
+    chapter
+        .get("path")
+        .ok_or_else(|| RenderError::new("No path found for chapter in JSON data"))
+        .and_then(|p| {
+            Path::new(p)
+                .with_extension("html")
+                .to_str()
+                .ok_or_else(|| RenderError::new("Link could not be converted to str"))
+                .map(|p| context.insert("link".to_owned(), json!(p.replace("\\", "/"))))
+        })?;
 
     trace!("Render template");
 
@@ -138,14 +138,14 @@ pub fn next(_h: &Helper, r: &Handlebars, rc: &mut RenderContext) -> Result<(), R
 
 #[cfg(test)]
 mod tests {
-   use super::*;
+    use super::*;
 
-   static TEMPLATE: &'static str =
-      "{{#previous}}{{title}}: {{link}}{{/previous}}|{{#next}}{{title}}: {{link}}{{/next}}";
+    static TEMPLATE: &'static str =
+        "{{#previous}}{{title}}: {{link}}{{/previous}}|{{#next}}{{title}}: {{link}}{{/next}}";
 
-   #[test]
-   fn test_next_previous() {
-      let data = json!({
+    #[test]
+    fn test_next_previous() {
+        let data = json!({
          "name": "two",
          "path": "two.path",
          "chapters": [
@@ -164,18 +164,19 @@ mod tests {
          ]
       });
 
-      let mut h = Handlebars::new();
-      h.register_helper("previous", Box::new(previous));
-      h.register_helper("next", Box::new(next));
+        let mut h = Handlebars::new();
+        h.register_helper("previous", Box::new(previous));
+        h.register_helper("next", Box::new(next));
 
-      assert_eq!(
-         h.template_render(TEMPLATE, &data).unwrap(),
-         "one: one.html|three: three.html");
-   }
+        assert_eq!(
+            h.render_template(TEMPLATE, &data).unwrap(),
+            "one: one.html|three: three.html"
+        );
+    }
 
-   #[test]
-   fn test_first() {
-      let data = json!({
+    #[test]
+    fn test_first() {
+        let data = json!({
          "name": "one",
          "path": "one.path",
          "chapters": [
@@ -194,17 +195,18 @@ mod tests {
          ]
       });
 
-      let mut h = Handlebars::new();
-      h.register_helper("previous", Box::new(previous));
-      h.register_helper("next", Box::new(next));
+        let mut h = Handlebars::new();
+        h.register_helper("previous", Box::new(previous));
+        h.register_helper("next", Box::new(next));
 
-      assert_eq!(
-         h.template_render(TEMPLATE, &data).unwrap(),
-         "|two: two.html");
-   }
-   #[test]
-   fn test_last() {
-      let data = json!({
+        assert_eq!(
+            h.render_template(TEMPLATE, &data).unwrap(),
+            "|two: two.html"
+        );
+    }
+    #[test]
+    fn test_last() {
+        let data = json!({
          "name": "three",
          "path": "three.path",
          "chapters": [
@@ -223,12 +225,13 @@ mod tests {
          ]
       });
 
-      let mut h = Handlebars::new();
-      h.register_helper("previous", Box::new(previous));
-      h.register_helper("next", Box::new(next));
+        let mut h = Handlebars::new();
+        h.register_helper("previous", Box::new(previous));
+        h.register_helper("next", Box::new(next));
 
-      assert_eq!(
-         h.template_render(TEMPLATE, &data).unwrap(),
-         "two: two.html|");
-   }
+        assert_eq!(
+            h.render_template(TEMPLATE, &data).unwrap(),
+            "two: two.html|"
+        );
+    }
 }

src/renderer/html_handlebars/helpers/toc.rs

@@ -8,7 +8,7 @@ use pulldown_cmark::{html, Event, Parser, Tag};
 // Handlebars helper to construct TOC
 #[derive(Clone, Copy)]
 pub struct RenderToc {
-    pub no_section_label: bool
+    pub no_section_label: bool,
 }
 
 impl HelperDef for RenderToc {
@@ -16,14 +16,14 @@ impl HelperDef for RenderToc {
         // get value from context data
         // rc.get_path() is current json parent path, you should always use it like this
         // param is the key of value you want to display
-        let chapters = rc.evaluate_absolute("chapters").and_then(|c| {
+        let chapters = rc.evaluate_absolute("chapters", true).and_then(|c| {
             serde_json::value::from_value::<Vec<BTreeMap<String, String>>>(c.clone())
                 .map_err(|_| RenderError::new("Could not decode the JSON data"))
         })?;
-        let current = rc.evaluate_absolute("path")?
-                        .as_str()
-                        .ok_or_else(|| RenderError::new("Type error for `path`, string expected"))?
-                        .replace("\"", "");
+        let current = rc.evaluate_absolute("path", true)?
+            .as_str()
+            .ok_or_else(|| RenderError::new("Type error for `path`, string expected"))?
+            .replace("\"", "");
 
         rc.writer.write_all(b"<ol class=\"chapter\">")?;
 
@@ -107,12 +107,12 @@ impl HelperDef for RenderToc {
 
                 // filter all events that are not inline code blocks
                 let parser = Parser::new(name).filter(|event| match *event {
-                                                          Event::Start(Tag::Code) |
-                                                          Event::End(Tag::Code) |
-                                                          Event::InlineHtml(_) |
-                                                          Event::Text(_) => true,
-                                                          _ => false,
-                                                      });
+                    Event::Start(Tag::Code)
+                    | Event::End(Tag::Code)
+                    | Event::InlineHtml(_)
+                    | Event::Text(_) => true,
+                    _ => false,
+                });
 
                 // render markdown to html
                 let mut markdown_parsed_name = String::with_capacity(name.len() * 3 / 2);

src/renderer/html_handlebars/mod.rs

@@ -4,3 +4,6 @@ pub use self::hbs_renderer::HtmlHandlebars;
 
 mod hbs_renderer;
 mod helpers;
+
+#[cfg(feature = "search")]
+mod search;

src/renderer/html_handlebars/search.rs

@@ -0,0 +1,231 @@
+extern crate ammonia;
+extern crate elasticlunr;
+
+use std::borrow::Cow;
+use std::collections::{HashMap, HashSet};
+use std::path::Path;
+
+use pulldown_cmark::*;
+use serde_json;
+use self::elasticlunr::Index;
+
+use book::{Book, BookItem};
+use config::Search;
+use errors::*;
+use utils;
+use theme::searcher;
+
+/// Creates all files required for search.
+pub fn create_files(search_config: &Search, destination: &Path, book: &Book) -> Result<()> {
+    let mut index = Index::new(&["title", "body", "breadcrumbs"]);
+
+    for item in book.iter() {
+        render_item(&mut index, &search_config, item)?;
+    }
+
+    let index = write_to_js(index, &search_config)?;
+    debug!("Writing search index ✓");
+
+    if search_config.copy_js {
+        utils::fs::write_file(destination, "searchindex.js", index.as_bytes())?;
+        utils::fs::write_file(destination, "searcher.js", searcher::JS)?;
+        utils::fs::write_file(destination, "mark.min.js", searcher::MARK_JS)?;
+        utils::fs::write_file(destination, "elasticlunr.min.js", searcher::ELASTICLUNR_JS)?;
+        debug!("Copying search files ✓");
+    }
+
+    Ok(())
+}
+
+/// Uses the given arguments to construct a search document, then inserts it to the given index.
+fn add_doc<'a>(
+    index: &mut Index,
+    anchor_base: &'a str,
+    section_id: &Option<String>,
+    items: &[&str],
+) {
+    let doc_ref: Cow<'a, str> = if let &Some(ref id) = section_id {
+        format!("{}#{}", anchor_base, id).into()
+    } else {
+        anchor_base.into()
+    };
+    let doc_ref = utils::collapse_whitespace(doc_ref.trim());
+    let items = items.iter().map(|&x| utils::collapse_whitespace(x.trim()));
+    index.add_doc(&doc_ref, items);
+}
+
+/// Renders markdown into flat unformatted text and adds it to the search index.
+fn render_item(
+    index: &mut Index,
+    search_config: &Search,
+    item: &BookItem,
+) -> Result<()> {
+    let chapter = match item {
+        &BookItem::Chapter(ref ch) => ch,
+        _ => return Ok(()),
+    };
+
+    let filepath = Path::new(&chapter.path).with_extension("html");
+    let filepath = filepath
+        .to_str()
+        .chain_err(|| "Could not convert HTML path to str")?;
+    let anchor_base = utils::fs::normalize_path(filepath);
+
+    let mut opts = Options::empty();
+    opts.insert(OPTION_ENABLE_TABLES);
+    opts.insert(OPTION_ENABLE_FOOTNOTES);
+    let p = Parser::new_ext(&chapter.content, opts);
+
+    let mut in_header = false;
+    let max_section_depth = search_config.heading_split_level as i32;
+    let mut section_id = None;
+    let mut heading = String::new();
+    let mut body = String::new();
+    let mut breadcrumbs = chapter.parent_names.clone();
+    let mut footnote_numbers = HashMap::new();
+
+    for event in p {
+        match event {
+            Event::Start(Tag::Header(i)) if i <= max_section_depth => {
+                if heading.len() > 0 {
+                    // Section finished, the next header is following now
+                    // Write the data to the index, and clear it for the next section
+                    add_doc(
+                        index,
+                        &anchor_base,
+                        &section_id,
+                        &[&heading, &body, &breadcrumbs.join(" » ")],
+                    );
+                    section_id = None;
+                    heading.clear();
+                    body.clear();
+                    breadcrumbs.pop();
+                }
+
+                in_header = true;
+            }
+            Event::End(Tag::Header(i)) if i <= max_section_depth => {
+                in_header = false;
+                section_id = Some(utils::id_from_content(&heading));
+                breadcrumbs.push(heading.clone());
+            }
+            Event::Start(Tag::FootnoteDefinition(name)) => {
+                let number = footnote_numbers.len() + 1;
+                footnote_numbers.entry(name).or_insert(number);
+            }
+            Event::Start(_) | Event::End(_) | Event::SoftBreak | Event::HardBreak => {
+                // Insert spaces where HTML output would usually seperate text
+                // to ensure words don't get merged together
+                if in_header {
+                    heading.push(' ');
+                } else {
+                    body.push(' ');
+                }
+            }
+            Event::Text(text) => {
+                if in_header {
+                    heading.push_str(&text);
+                } else {
+                    body.push_str(&text);
+                }
+            }
+            Event::Html(html) | Event::InlineHtml(html) => {
+                body.push_str(&clean_html(&html));
+            }
+            Event::FootnoteReference(name) => {
+                let len = footnote_numbers.len() + 1;
+                let number = footnote_numbers.entry(name).or_insert(len);
+                body.push_str(&format!(" [{}] ", number));
+            }
+        }
+    }
+
+    if heading.len() > 0 {
+        // Make sure the last section is added to the index
+        add_doc(
+            index,
+            &anchor_base,
+            &section_id,
+            &[&heading, &body, &breadcrumbs.join(" » ")],
+        );
+    }
+
+    Ok(())
+}
+
+/// Exports the index and search options to a JS script which stores the index in `window.search`.
+/// Using a JS script is a workaround for CORS in `file://` URIs. It also removes the need for
+/// downloading/parsing JSON in JS.
+fn write_to_js(index: Index, search_config: &Search) -> Result<String> {
+    use std::collections::BTreeMap;
+    use self::elasticlunr::config::{SearchBool, SearchOptions, SearchOptionsField};
+
+    #[derive(Serialize)]
+    struct ResultsOptions {
+        limit_results: u32,
+        teaser_word_count: u32,
+    }
+
+    #[derive(Serialize)]
+    struct SearchindexJson {
+        /// The options used for displaying search results
+        resultsoptions: ResultsOptions,
+        /// The searchoptions for elasticlunr.js
+        searchoptions: SearchOptions,
+        /// The index for elasticlunr.js
+        index: elasticlunr::Index,
+    }
+
+    let mut fields = BTreeMap::new();
+    let mut opt = SearchOptionsField::default();
+    opt.boost = Some(search_config.boost_title);
+    fields.insert("title".into(), opt);
+    opt.boost = Some(search_config.boost_paragraph);
+    fields.insert("body".into(), opt);
+    opt.boost = Some(search_config.boost_hierarchy);
+    fields.insert("breadcrumbs".into(), opt);
+
+    let searchoptions = SearchOptions {
+        bool: if search_config.use_boolean_and {
+            SearchBool::And
+        } else {
+            SearchBool::Or
+        },
+        expand: search_config.expand,
+        fields,
+    };
+
+    let resultsoptions = ResultsOptions {
+        limit_results: search_config.limit_results,
+        teaser_word_count: search_config.teaser_word_count,
+    };
+
+    let json_contents = SearchindexJson {
+        resultsoptions,
+        searchoptions,
+        index,
+    };
+    let json_contents = serde_json::to_string(&json_contents)?;
+
+    Ok(format!("window.search = {};", json_contents))
+}
+
+fn clean_html(html: &str) -> String {
+    lazy_static! {
+        static ref AMMONIA: ammonia::Builder<'static> = {
+            let mut clean_content = HashSet::new();
+            clean_content.insert("script");
+            clean_content.insert("style");
+            let mut builder = ammonia::Builder::new();
+            builder
+                .tags(HashSet::new())
+                .tag_attributes(HashMap::new())
+                .generic_attributes(HashSet::new())
+                .link_rel(None)
+                .allowed_classes(HashMap::new())
+                .clean_content_tags(clean_content);
+            builder
+        };
+    }
+    AMMONIA.clean(html).to_string()
+}

src/renderer/mod.rs

@@ -16,7 +16,7 @@ pub use self::html_handlebars::HtmlHandlebars;
 mod html_handlebars;
 
 use std::fs;
-use std::io::Read;
+use std::io::{self, Read};
 use std::path::PathBuf;
 use std::process::{Command, Stdio};
 use serde_json;
@@ -26,6 +26,8 @@ use errors::*;
 use config::Config;
 use book::Book;
 
+const MDBOOK_VERSION: &str = env!("CARGO_PKG_VERSION");
+
 /// An arbitrary `mdbook` backend.
 ///
 /// Although it's quite possible for you to import `mdbook` as a library and
@@ -68,7 +70,7 @@ pub struct RenderContext {
 
 impl RenderContext {
     /// Create a new `RenderContext`.
-    pub(crate) fn new<P, Q>(root: P, book: Book, config: Config, destination: Q) -> RenderContext
+    pub fn new<P, Q>(root: P, book: Book, config: Config, destination: Q) -> RenderContext
     where
         P: Into<PathBuf>,
         Q: Into<PathBuf>,
@@ -76,7 +78,7 @@ impl RenderContext {
         RenderContext {
             book: book,
             config: config,
-            version: env!("CARGO_PKG_VERSION").to_string(),
+            version: MDBOOK_VERSION.to_string(),
             root: root.into(),
             destination: destination.into(),
         }
@@ -155,13 +157,22 @@ impl Renderer for CmdRenderer {
 
         let _ = fs::create_dir_all(&ctx.destination);
 
-        let mut child = self.compose_command()?
+        let mut child = match self.compose_command()?
             .stdin(Stdio::piped())
             .stdout(Stdio::inherit())
             .stderr(Stdio::inherit())
             .current_dir(&ctx.destination)
-            .spawn()
-            .chain_err(|| "Unable to start the renderer")?;
+            .spawn() {
+                Ok(c) => c,
+                Err(ref e) if e.kind() == io::ErrorKind::NotFound => {
+                    warn!("The command wasn't found, is the \"{}\" backend installed?", self.name);
+                    warn!("\tCommand: {}", self.cmd);
+                    return Ok(());
+                }
+                Err(e) => {
+                    return Err(e).chain_err(|| "Unable to start the backend")?;
+                }
+            };
 
         {
             let mut stdin = child.stdin.take().expect("Child has stdin");

src/theme/book.css

@@ -36,6 +36,15 @@ h5 {
 .header + .header h5 {
   margin-top: 1em;
 }
+a.header:target h1:before,
+a.header:target h2:before,
+a.header:target h3:before,
+a.header:target h4:before {
+  display: inline-block;
+  content: "»";
+  margin-left: -30px;
+  width: 30px;
+}
 table {
   margin: 0 auto;
   border-collapse: collapse;
@@ -47,6 +56,17 @@ table td {
 table thead td {
   font-weight: 700;
 }
+:not(.footnote-definition) + .footnote-definition,
+.footnote-definition + :not(.footnote-definition) {
+  margin-top: 2em;
+}
+.footnote-definition {
+  font-size: 0.9em;
+  margin: 0.5em 0;
+}
+.footnote-definition p {
+  display: inline;
+}
 .sidebar {
   position: fixed;
   left: 0;
@@ -60,6 +80,7 @@ table thead td {
   -moz-box-sizing: border-box;
   box-sizing: border-box;
   -webkit-overflow-scrolling: touch;
+  overscroll-behavior-y: contain;
   -webkit-transition: -webkit-transform 0.5s;
   -moz-transition: -moz-transform 0.5s;
   -o-transition: -o-transform 0.5s;
@@ -83,16 +104,26 @@ table thead td {
 }
 .chapter li a {
   display: block;
-  padding: 5px 0;
+  padding: 0;
   text-decoration: none;
 }
+@media (-moz-touch-enabled: 1), (pointer: coarse) {
+  .chapter li a {
+    padding: 5px 0;
+  }
+}
 .chapter li a:hover {
   text-decoration: none;
 }
 .chapter .spacer {
   width: 100%;
   height: 3px;
-  margin: 10px 0px;
+  margin: 5px 0px;
+}
+@media (-moz-touch-enabled: 1), (pointer: coarse) {
+  .chapter .spacer {
+    margin: 10px 0;
+  }
 }
 .section {
   list-style: none outside none;
@@ -106,33 +137,45 @@ table thead td {
   white-space: nowrap;
 }
 .page-wrapper {
+  left: 0;
+  position: absolute;
+  right: 0;
+  top: 0;
+  bottom: 0;
   -webkit-box-sizing: border-box;
   -moz-box-sizing: border-box;
   box-sizing: border-box;
-  -webkit-transition: padding-left 0.5s, margin-left 0.5s;
-  -moz-transition: padding-left 0.5s, margin-left 0.5s;
-  -o-transition: padding-left 0.5s, margin-left 0.5s;
-  -ms-transition: padding-left 0.5s, margin-left 0.5s;
-  transition: padding-left 0.5s, margin-left 0.5s;
+  -webkit-transition: padding-left 0.5s, margin-left 0.5s, left 0.5s;
+  -moz-transition: padding-left 0.5s, margin-left 0.5s, left 0.5s;
+  -o-transition: padding-left 0.5s, margin-left 0.5s, left 0.5s;
+  -ms-transition: padding-left 0.5s, margin-left 0.5s, left 0.5s;
+  transition: padding-left 0.5s, margin-left 0.5s, left 0.5s;
 }
 .sidebar-visible .page-wrapper {
-  padding-left: 300px;
-}
-@media only screen and (max-width: 1079px) {
-  .sidebar-visible .page-wrapper {
-    padding-left: 0;
-    margin-left: 300px;
-  }
+  left: 300px;
 }
 .page {
   outline: 0;
   padding: 0 15px;
 }
 .content {
+  position: relative;
+  top: 0;
+  bottom: 0;
+  overflow-y: auto;
+  right: 0;
+  left: 0;
+  padding: 0 15px;
+  padding-bottom: 50px;
+}
+.sidebar-visible .content {
+  position: absolute;
+  top: 52px;
+}
+.content > main {
   margin-left: auto;
   margin-right: auto;
   max-width: 750px;
-  padding-bottom: 50px;
 }
 .content a {
   text-decoration: none;
@@ -209,6 +252,7 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
   overflow: hidden;
   -o-text-overflow: ellipsis;
   text-overflow: ellipsis;
+  cursor: pointer;
 }
 .nav-chapters {
   font-size: 2.5em;
@@ -314,6 +358,7 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
   color: #333;
   background-color: #fff;
 /* Inline code */
+/* Search */
 }
 .light .content .header:link,
 .light .content .header:visited {
@@ -340,6 +385,12 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
   background-color: #fafafa;
   color: #364149;
 }
+.light .sidebar::-webkit-scrollbar {
+  background: #fafafa;
+}
+.light .sidebar::-webkit-scrollbar-thumb {
+  background: #ccc;
+}
 .light .chapter li {
   color: #aaa;
 }
@@ -376,6 +427,7 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .light .mobile-nav-chapters {
   background-color: #fafafa;
 }
+.light #searchresults a,
 .light .content a:link,
 .light a:visited,
 .light a > .hljs {
@@ -464,10 +516,40 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .light .icon-button i {
   margin: 0;
 }
+.light ::-webkit-scrollbar {
+  background: #fff;
+}
+.light ::-webkit-scrollbar-thumb {
+  background: #ccc;
+}
+.light #searchbar {
+  border: 1px solid #aaa;
+  border-radius: 3px;
+  background-color: #fafafa;
+  color: #000;
+}
+.light #searchbar:focus,
+.light #searchbar.active {
+  -webkit-box-shadow: 0 0 3px #aaa;
+  box-shadow: 0 0 3px #aaa;
+}
+.light .searchresults-header {
+  color: #666;
+}
+.light .searchresults-outer {
+  border-bottom: 1px dashed #888;
+}
+.light ul#searchresults li.focus {
+  background-color: #e4f2fe;
+}
+.light mark {
+  background-color: #a2cff5;
+}
 .coal {
   color: #98a3ad;
   background-color: #141617;
 /* Inline code */
+/* Search */
 }
 .coal .content .header:link,
 .coal .content .header:visited {
@@ -494,6 +576,12 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
   background-color: #292c2f;
   color: #a1adb8;
 }
+.coal .sidebar::-webkit-scrollbar {
+  background: #292c2f;
+}
+.coal .sidebar::-webkit-scrollbar-thumb {
+  background: #a1adb8;
+}
 .coal .chapter li {
   color: #505254;
 }
@@ -530,6 +618,7 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .coal .mobile-nav-chapters {
   background-color: #292c2f;
 }
+.coal #searchresults a,
 .coal .content a:link,
 .coal a:visited,
 .coal a > .hljs {
@@ -618,10 +707,40 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .coal .icon-button i {
   margin: 0;
 }
+.coal ::-webkit-scrollbar {
+  background: #141617;
+}
+.coal ::-webkit-scrollbar-thumb {
+  background: #a1adb8;
+}
+.coal #searchbar {
+  border: 1px solid #aaa;
+  border-radius: 3px;
+  background-color: #b7b7b7;
+  color: #000;
+}
+.coal #searchbar:focus,
+.coal #searchbar.active {
+  -webkit-box-shadow: 0 0 3px #aaa;
+  box-shadow: 0 0 3px #aaa;
+}
+.coal .searchresults-header {
+  color: #666;
+}
+.coal .searchresults-outer {
+  border-bottom: 1px dashed #98a3ad;
+}
+.coal ul#searchresults li.focus {
+  background-color: #2b2b2f;
+}
+.coal mark {
+  background-color: #355c7d;
+}
 .navy {
   color: #bcbdd0;
   background-color: #161923;
 /* Inline code */
+/* Search */
 }
 .navy .content .header:link,
 .navy .content .header:visited {
@@ -648,6 +767,12 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
   background-color: #282d3f;
   color: #c8c9db;
 }
+.navy .sidebar::-webkit-scrollbar {
+  background: #282d3f;
+}
+.navy .sidebar::-webkit-scrollbar-thumb {
+  background: #c8c9db;
+}
 .navy .chapter li {
   color: #505274;
 }
@@ -684,6 +809,7 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .navy .mobile-nav-chapters {
   background-color: #282d3f;
 }
+.navy #searchresults a,
 .navy .content a:link,
 .navy a:visited,
 .navy a > .hljs {
@@ -772,10 +898,40 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .navy .icon-button i {
   margin: 0;
 }
+.navy ::-webkit-scrollbar {
+  background: #161923;
+}
+.navy ::-webkit-scrollbar-thumb {
+  background: #c8c9db;
+}
+.navy #searchbar {
+  border: 1px solid #aaa;
+  border-radius: 3px;
+  background-color: #aeaec6;
+  color: #000;
+}
+.navy #searchbar:focus,
+.navy #searchbar.active {
+  -webkit-box-shadow: 0 0 3px #aaa;
+  box-shadow: 0 0 3px #aaa;
+}
+.navy .searchresults-header {
+  color: #5f5f71;
+}
+.navy .searchresults-outer {
+  border-bottom: 1px dashed #5c5c68;
+}
+.navy ul#searchresults li.focus {
+  background-color: #242430;
+}
+.navy mark {
+  background-color: #a2cff5;
+}
 .rust {
   color: #262625;
   background-color: #e1e1db;
 /* Inline code */
+/* Search */
 }
 .rust .content .header:link,
 .rust .content .header:visited {
@@ -802,6 +958,12 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
   background-color: #3b2e2a;
   color: #c8c9db;
 }
+.rust .sidebar::-webkit-scrollbar {
+  background: #3b2e2a;
+}
+.rust .sidebar::-webkit-scrollbar-thumb {
+  background: #c8c9db;
+}
 .rust .chapter li {
   color: #505254;
 }
@@ -838,6 +1000,7 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .rust .mobile-nav-chapters {
   background-color: #3b2e2a;
 }
+.rust #searchresults a,
 .rust .content a:link,
 .rust a:visited,
 .rust a > .hljs {
@@ -926,10 +1089,40 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .rust .icon-button i {
   margin: 0;
 }
+.rust ::-webkit-scrollbar {
+  background: #e1e1db;
+}
+.rust ::-webkit-scrollbar-thumb {
+  background: #c8c9db;
+}
+.rust #searchbar {
+  border: 1px solid #aaa;
+  border-radius: 3px;
+  background-color: #fafafa;
+  color: #000;
+}
+.rust #searchbar:focus,
+.rust #searchbar.active {
+  -webkit-box-shadow: 0 0 3px #aaa;
+  box-shadow: 0 0 3px #aaa;
+}
+.rust .searchresults-header {
+  color: #666;
+}
+.rust .searchresults-outer {
+  border-bottom: 1px dashed #888;
+}
+.rust ul#searchresults li.focus {
+  background-color: #dec2a2;
+}
+.rust mark {
+  background-color: #e69f67;
+}
 .ayu {
   color: #c5c5c5;
   background-color: #0f1419;
 /* Inline code */
+/* Search */
 }
 .ayu .content .header:link,
 .ayu .content .header:visited {
@@ -956,6 +1149,12 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
   background-color: #14191f;
   color: #c8c9db;
 }
+.ayu .sidebar::-webkit-scrollbar {
+  background: #14191f;
+}
+.ayu .sidebar::-webkit-scrollbar-thumb {
+  background: #c8c9db;
+}
 .ayu .chapter li {
   color: #5c6773;
 }
@@ -992,6 +1191,7 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .ayu .mobile-nav-chapters {
   background-color: #14191f;
 }
+.ayu #searchresults a,
 .ayu .content a:link,
 .ayu a:visited,
 .ayu a > .hljs {
@@ -1080,6 +1280,35 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .ayu .icon-button i {
   margin: 0;
 }
+.ayu ::-webkit-scrollbar {
+  background: #0f1419;
+}
+.ayu ::-webkit-scrollbar-thumb {
+  background: #c8c9db;
+}
+.ayu #searchbar {
+  border: 1px solid #848484;
+  border-radius: 3px;
+  background-color: #424242;
+  color: #fff;
+}
+.ayu #searchbar:focus,
+.ayu #searchbar.active {
+  -webkit-box-shadow: 0 0 3px #d4c89f;
+  box-shadow: 0 0 3px #d4c89f;
+}
+.ayu .searchresults-header {
+  color: #666;
+}
+.ayu .searchresults-outer {
+  border-bottom: 1px dashed #888;
+}
+.ayu ul#searchresults li.focus {
+  background-color: #252932;
+}
+.ayu mark {
+  background-color: #e3b171;
+}
 @media only print {
   #sidebar,
   #menu-bar,
@@ -1160,3 +1389,66 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
 .tooltipped .tooltiptext {
   visibility: visible;
 }
+#searchresults a {
+  text-decoration: none;
+}
+mark {
+  border-radius: 2px;
+  padding: 0 3px 1px 3px;
+  margin: 0 -3px -1px -3px;
+  -webkit-transition: background-color 300ms linear;
+  -moz-transition: background-color 300ms linear;
+  -o-transition: background-color 300ms linear;
+  -ms-transition: background-color 300ms linear;
+  transition: background-color 300ms linear;
+}
+.fade-out {
+  background-color: rgba(0,0,0,0) !important;
+}
+.searchbar-outer {
+  display: none;
+  margin-left: auto;
+  margin-right: auto;
+  max-width: 750px;
+}
+#searchbar {
+  display: block;
+  width: 100%;
+  margin: 5px auto 0px auto;
+  padding: 10px 16px;
+  -webkit-transition: box-shadow 300ms ease-in-out;
+  -moz-transition: box-shadow 300ms ease-in-out;
+  -o-transition: box-shadow 300ms ease-in-out;
+  -ms-transition: box-shadow 300ms ease-in-out;
+  transition: box-shadow 300ms ease-in-out;
+}
+.searchresults-header {
+  font-weight: bold;
+  font-size: 1em;
+  padding: 18px 0 0 5px;
+}
+.searchresults-outer {
+  display: none;
+  margin-left: auto;
+  margin-right: auto;
+  max-width: 750px;
+}
+ul#searchresults {
+  list-style: none;
+  padding-left: 20px;
+}
+ul#searchresults li {
+  margin: 10px 0px;
+  padding: 2px;
+  border-radius: 2px;
+}
+ul#searchresults span.teaser {
+  display: block;
+  clear: both;
+  margin: 5px 0 0 20px;
+  font-size: 0.8em;
+}
+ul#searchresults span.teaser em {
+  font-weight: bold;
+  font-style: normal;
+}

src/theme/book.js

@@ -172,7 +172,7 @@ function playpen_text(playpen) {
 
         var buttons = document.createElement('div');
         buttons.className = 'buttons';
-        buttons.innerHTML = "<i class=\"fa fa-expand\" title=\"Show hidden lines\"></i>";
+        buttons.innerHTML = "<button class=\"fa fa-expand\" title=\"Show hidden lines\" aria-label=\"Show hidden lines\"></button>";
 
         // add expand button
         pre_block.prepend(buttons);
@@ -184,6 +184,7 @@ function playpen_text(playpen) {
                 e.target.classList.remove('fa-expand');
                 e.target.classList.add('fa-compress');
                 e.target.title = 'Hide lines';
+                e.target.setAttribute('aria-label', e.target.title);
 
                 Array.from(lines).forEach(function (line) {
                     line.classList.remove('hidden');
@@ -195,6 +196,7 @@ function playpen_text(playpen) {
                 e.target.classList.remove('fa-compress');
                 e.target.classList.add('fa-expand');
                 e.target.title = 'Show hidden lines';
+                e.target.setAttribute('aria-label', e.target.title);
 
                 Array.from(lines).forEach(function (line) {
                     line.classList.remove('unhidden');
@@ -217,6 +219,7 @@ function playpen_text(playpen) {
             var clipButton = document.createElement('button');
             clipButton.className = 'fa fa-copy clip-button';
             clipButton.title = 'Copy to clipboard';
+            clipButton.setAttribute('aria-label', clipButton.title);
             clipButton.innerHTML = '<i class=\"tooltiptext\"></i>';
 
             buttons.prepend(clipButton);
@@ -237,11 +240,13 @@ function playpen_text(playpen) {
         runCodeButton.className = 'fa fa-play play-button';
         runCodeButton.hidden = true;
         runCodeButton.title = 'Run this code';
+        runCodeButton.setAttribute('aria-label', runCodeButton.title);
 
         var copyCodeClipboardButton = document.createElement('button');
         copyCodeClipboardButton.className = 'fa fa-copy clip-button';
         copyCodeClipboardButton.innerHTML = '<i class="tooltiptext"></i>';
         copyCodeClipboardButton.title = 'Copy to clipboard';
+        copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title);
 
         buttons.prepend(runCodeButton);
         buttons.prepend(copyCodeClipboardButton);
@@ -255,6 +260,7 @@ function playpen_text(playpen) {
             var undoChangesButton = document.createElement('button');
             undoChangesButton.className = 'fa fa-history reset-button';
             undoChangesButton.title = 'Undo changes';
+            undoChangesButton.setAttribute('aria-label', undoChangesButton.title);
 
             buttons.prepend(undoChangesButton);
 
@@ -279,6 +285,7 @@ function playpen_text(playpen) {
 })();
 
 (function themes() {
+    var html = document.querySelector('html');
     var themeToggleButton = document.getElementById('theme-toggle');
     var themePopup = document.getElementById('theme-list');
     var themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
@@ -291,11 +298,13 @@ function playpen_text(playpen) {
     function showThemes() {
         themePopup.style.display = 'block';
         themeToggleButton.setAttribute('aria-expanded', true);
+        themePopup.querySelector("button#" + document.body.className).focus();
     }
 
     function hideThemes() {
         themePopup.style.display = 'none';
         themeToggleButton.setAttribute('aria-expanded', false);
+        themeToggleButton.focus();
     }
 
     function set_theme(theme) {
@@ -331,9 +340,15 @@ function playpen_text(playpen) {
             });
         }
 
+        var previousTheme;
+        try { previousTheme = localStorage.getItem('mdbook-theme'); } catch (e) { }
+        if (previousTheme === null || previousTheme === undefined) { previousTheme = 'light'; }
+
         try { localStorage.setItem('mdbook-theme', theme); } catch (e) { }
 
         document.body.className = theme;
+        html.classList.remove(previousTheme);
+        html.classList.add(theme);
     }
 
     // Set theme
@@ -356,19 +371,51 @@ function playpen_text(playpen) {
         set_theme(theme);
     });
 
-    // Hide theme selector popup when clicking outside of it
-    document.addEventListener('click', function (event) {
-        if (themePopup.style.display === 'block' && !themeToggleButton.contains(event.target) && !themePopup.contains(event.target)) {
+    themePopup.addEventListener('focusout', function(e) {
+        // e.relatedTarget is null in Safari and Firefox on macOS (see workaround below)
+        if (!!e.relatedTarget && !themePopup.contains(e.relatedTarget)) {
+            hideThemes();
+        }
+    });
+
+    // Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang-nursery/mdBook/issues/628
+    document.addEventListener('click', function(e) {
+        if (themePopup.style.display === 'block' && !themeToggleButton.contains(e.target) && !themePopup.contains(e.target)) {
             hideThemes();
         }
     });
 
     document.addEventListener('keydown', function (e) {
+        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+        if (!themePopup.contains(e.target)) { return; }
+
         switch (e.key) {
             case 'Escape':
                 e.preventDefault();
                 hideThemes();
                 break;
+            case 'ArrowUp':
+                e.preventDefault();
+                var li = document.activeElement.parentElement;
+                if (li && li.previousElementSibling) {
+                    li.previousElementSibling.querySelector('button').focus();
+                }
+                break;
+            case 'ArrowDown':
+                e.preventDefault();
+                var li = document.activeElement.parentElement;
+                if (li && li.nextElementSibling) {
+                    li.nextElementSibling.querySelector('button').focus();
+                }
+                break;
+            case 'Home':
+                e.preventDefault();
+                themePopup.querySelector('li:first-child button').focus();
+                break;
+            case 'End':
+                e.preventDefault();
+                themePopup.querySelector('li:last-child button').focus();
+                break;
         }
     });
 })();
@@ -422,7 +469,7 @@ function playpen_text(playpen) {
             x: e.touches[0].clientX,
             time: Date.now()
         };
-    });
+    }, { passive: true });
 
     document.addEventListener('touchmove', function (e) {
         if (!firstContact)
@@ -440,7 +487,7 @@ function playpen_text(playpen) {
 
             firstContact = null;
         }
-    });
+    }, { passive: true });
 
     // Scroll sidebar to current active section
     var activeSection = sidebar.querySelector(".active");
@@ -452,6 +499,7 @@ function playpen_text(playpen) {
 (function chapterNavigation() {
     document.addEventListener('keydown', function (e) {
         if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+        if (window.search && window.search.hasFocus()) { return; }
 
         switch (e.key) {
             case 'ArrowRight':
@@ -509,6 +557,14 @@ function playpen_text(playpen) {
     });
 })();
 
+(function scrollToTop () {
+    var menuTitle = document.querySelector('.menu-title');
+
+    menuTitle.addEventListener('click', function () {
+        document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
+    });
+})();
+
 (function autoHideMenu() {
     var menu = document.getElementById('menu-bar');
 

src/theme/index.hbs

@@ -1,6 +1,7 @@
 <!DOCTYPE HTML>
-<html lang="{{ language }}">
+<html lang="{{ language }}" class="sidebar-visible">
     <head>
+        <!-- Book generated using mdBook -->
         <meta charset="UTF-8">
         <title>{{ title }}</title>
         <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
@@ -41,6 +42,14 @@
             }
         </script>
 
+        <noscript>
+            <style type="text/css">
+                .javascript-only {
+                    display: none;
+                }
+            </style>
+        </noscript>
+
     </head>
     <body class="light">
         <!-- Work around some values being stored in localStorage wrapped in quotes -->
@@ -65,16 +74,19 @@
             try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } 
             if (theme === null || theme === undefined) { theme = 'light'; }
             document.body.className = theme;
+            document.querySelector('html').className = theme;
         </script>
 
         <!-- Hide / unhide sidebar before it is displayed -->
         <script type="text/javascript">
+            var html = document.querySelector('html');
             var sidebar = 'hidden';
             if (document.body.clientWidth >= 1080) {
                 try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                 sidebar = sidebar || 'visible';
             }
-            document.querySelector('html').classList.add("sidebar-" + sidebar);
+            html.classList.remove('sidebar-visible');
+            html.classList.add("sidebar-" + sidebar);
         </script>
 
         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
@@ -87,32 +99,48 @@
                 {{> header}}
                 <div id="menu-bar" class="menu-bar">
                     <div id="menu-bar-sticky-container">
-                        <div class="left-buttons">
-                            <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-controls="sidebar">
+                        <div class="left-buttons javascript-only">
+                            <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                                 <i class="fa fa-bars"></i>
                             </button>
-                            <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                                 <i class="fa fa-paint-brush"></i>
                             </button>
-                            <ul id="theme-list" class="theme-popup" aria-label="submenu">
-                                <li><button class="theme" id="light">Light <span class="default">(default)</span></button></li>
-                                <li><button class="theme" id="rust">Rust</button></li>
-                                <li><button class="theme" id="coal">Coal</button></li>
-                                <li><button class="theme" id="navy">Navy</button></li>
-                                <li><button class="theme" id="ayu">Ayu</button></li>
+                            <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                                <li role="none"><button role="menuitem" class="theme" id="light">Light <span class="default">(default)</span></button></li>
+                                <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                                <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                                <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                                <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                             </ul>
+                            {{#if search_enabled}}
+                            <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                                <i class="fa fa-search"></i>
+                            </button>
+                            {{/if}}
                         </div>
 
-                        <h1 class="menu-title">{{ book_title }}</h1>
+                        <h1 class="menu-title">{{ book_title }}</h1> 
 
                         <div class="right-buttons">
-                            <a href="print.html" title="Print this book">
+                            <a href="print.html" title="Print this book" aria-label="Print this book">
                                 <i id="print-button" class="fa fa-print"></i>
                             </a>
                         </div>
                     </div>
                 </div>
 
+                {{#if search_enabled}}
+                <div id="searchbar-outer" class="searchbar-outer">
+                    <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                </div>
+                <div id="searchresults-outer" class="searchresults-outer">
+                    <div class="searchresults-header" id="searchresults-header"></div>
+                    <ul id="searchresults">
+                    </ul>
+                </div>
+                {{/if}}
+
                 <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                 <script type="text/javascript">
                     document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
@@ -130,13 +158,13 @@
                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
                         {{#previous}}
-                            <a rel="prev" href="{{link}}" class="mobile-nav-chapters previous" title="Previous chapter" aria-keyshortcuts="Left">
+                            <a rel="prev" href="{{link}}" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                 <i class="fa fa-angle-left"></i>
                             </a>
                         {{/previous}}
 
                         {{#next}}
-                            <a rel="next" href="{{link}}" class="mobile-nav-chapters next" title="Next chapter" aria-keyshortcuts="Right">
+                            <a rel="next" href="{{link}}" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>
                         {{/next}}
@@ -148,13 +176,13 @@
 
             <nav class="nav-wide-wrapper" aria-label="Page navigation">
                 {{#previous}}
-                    <a href="{{link}}" class="nav-chapters previous" title="Previous chapter" aria-keyshortcuts="Left">
+                    <a href="{{link}}" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                         <i class="fa fa-angle-left"></i>
                     </a>
                 {{/previous}}
 
                 {{#next}}
-                    <a href="{{link}}" class="nav-chapters next" title="Next chapter" aria-keyshortcuts="Right">
+                    <a href="{{link}}" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                         <i class="fa fa-angle-right"></i>
                     </a>
                 {{/next}}
@@ -210,12 +238,21 @@
         </script>
         {{/if}}
 
-        {{#if playpens_editable}}
-        <script src="{{ ace_js }}" type="text/javascript" charset="utf-8"></script>
-        <script src="{{ editor_js }}" type="text/javascript" charset="utf-8"></script>
-        <script src="{{ mode_rust_js }}" type="text/javascript" charset="utf-8"></script>
-        <script src="{{ theme_dawn_js }}" type="text/javascript" charset="utf-8"></script>
-        <script src="{{ theme_tomorrow_night_js }}" type="text/javascript" charset="utf-8"></script>
+        {{#if playpen_js}}
+        <script src="ace.js" type="text/javascript" charset="utf-8"></script>
+        <script src="editor.js" type="text/javascript" charset="utf-8"></script>
+        <script src="mode-rust.js" type="text/javascript" charset="utf-8"></script>
+        <script src="theme-dawn.js" type="text/javascript" charset="utf-8"></script>
+        <script src="theme-tomorrow_night.js" type="text/javascript" charset="utf-8"></script>
+        {{/if}}
+
+        {{#if search_enabled}}
+        <script src="searchindex.js" type="text/javascript" charset="utf-8"></script>
+        {{/if}}
+        {{#if search_js}}
+        <script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
+        <script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
+        <script src="searcher.js" type="text/javascript" charset="utf-8"></script>
         {{/if}}
 
         {{#if is_print}}

src/theme/mod.rs

@@ -1,6 +1,10 @@
-#![allow(missing_docs)] // FIXME: Document this
+#![allow(missing_docs)]
+
 pub mod playpen_editor;
 
+#[cfg(feature = "search")]
+pub mod searcher;
+
 use std::path::Path;
 use std::fs::File;
 use std::io::Read;
@@ -52,6 +56,8 @@ pub struct Theme {
 }
 
 impl Theme {
+    /// Creates a `Theme` from the given `theme_dir`.
+    /// If a file is found in the theme dir, it will override the default version.
     pub fn new<P: AsRef<Path>>(theme_dir: P) -> Self {
         let theme_dir = theme_dir.as_ref();
         let mut theme = Theme::default();
@@ -128,7 +134,7 @@ fn load_file_contents<P: AsRef<Path>>(filename: P, dest: &mut Vec<u8>) -> Result
 #[cfg(test)]
 mod tests {
     use super::*;
-    use tempdir::TempDir;
+    use tempfile::Builder as TempFileBuilder;
     use std::path::PathBuf;
 
     #[test]
@@ -153,7 +159,7 @@ mod tests {
             .map(|f| f.path())
             .filter(|p| p.is_file() && !p.ends_with(".rs"));
 
-        let temp = TempDir::new("mdbook").unwrap();
+        let temp = TempFileBuilder::new().prefix("mdbook").tempdir().unwrap();
 
         // "touch" all of the special files so we have empty copies
         for special_file in special_files {

src/theme/playpen_editor/mod.rs

@@ -1,70 +1,7 @@
-use std::path::Path;
-
-use theme::load_file_contents;
+//! Theme dependencies for the playpen editor.
 
 pub static JS: &'static [u8] = include_bytes!("editor.js");
 pub static ACE_JS: &'static [u8] = include_bytes!("ace.js");
 pub static MODE_RUST_JS: &'static [u8] = include_bytes!("mode-rust.js");
 pub static THEME_DAWN_JS: &'static [u8] = include_bytes!("theme-dawn.js");
 pub static THEME_TOMORROW_NIGHT_JS: &'static [u8] = include_bytes!("theme-tomorrow_night.js");
-
-/// Integration of a JavaScript editor for playpens.
-/// Uses the Ace editor: https://ace.c9.io/.
-/// The Ace editor itself, the mode, and the theme files are the
-/// generated minified no conflict versions.
-///
-/// The `PlaypenEditor` struct should be used instead of the static variables because
-/// the `new()` method
-/// will look if the user has an editor directory in his source folder and use
-/// the users editor instead
-/// of the default.
-///
-/// You should exceptionnaly use the static variables only if you need the
-/// default editor even if the
-/// user has specified another editor.
-pub struct PlaypenEditor {
-    pub js: Vec<u8>,
-    pub ace_js: Vec<u8>,
-    pub mode_rust_js: Vec<u8>,
-    pub theme_dawn_js: Vec<u8>,
-    pub theme_tomorrow_night_js: Vec<u8>,
-}
-
-impl PlaypenEditor {
-    pub fn new(src: &Path) -> Self {
-        let mut editor = PlaypenEditor {
-            js: JS.to_owned(),
-            ace_js: ACE_JS.to_owned(),
-            mode_rust_js: MODE_RUST_JS.to_owned(),
-            theme_dawn_js: THEME_DAWN_JS.to_owned(),
-            theme_tomorrow_night_js: THEME_TOMORROW_NIGHT_JS.to_owned(),
-        };
-
-        // Check if the given path exists
-        if !src.exists() || !src.is_dir() {
-            return editor;
-        }
-
-        // Check for individual files if they exist
-        {
-            let files = vec![(src.join("editor.js"), &mut editor.js),
-                             (src.join("ace.js"), &mut editor.ace_js),
-                             (src.join("mode-rust.js"), &mut editor.mode_rust_js),
-                             (src.join("theme-dawn.js"), &mut editor.theme_dawn_js),
-                             (src.join("theme-tomorrow_night.js"),
-                             &mut editor.theme_tomorrow_night_js)];
-
-            for (filename, dest) in files {
-                if !filename.exists() {
-                    continue;
-                }
-
-                if let Err(e) = load_file_contents(&filename, dest) {
-                    warn!("Couldn't load custom file, {}: {}", filename.display(), e);
-                }
-            }
-        }
-
-        editor
-    }
-}

src/theme/searcher/mod.rs

@@ -0,0 +1,6 @@
+//! Theme dependencies for in-browser search. Not included in mdbook when
+//! the "search" cargo feature is disabled.
+
+pub static JS: &'static [u8] = include_bytes!("searcher.js");
+pub static MARK_JS: &'static [u8] = include_bytes!("mark.min.js");
+pub static ELASTICLUNR_JS: &'static [u8] = include_bytes!("elasticlunr.min.js");

src/theme/searcher/searcher.js

@@ -0,0 +1,464 @@
+window.search = window.search || {};
+(function search(search) {
+    // Search functionality
+    //
+    // You can use !hasFocus() to prevent keyhandling in your key
+    // event handlers while the user is typing his search.
+
+    if (!Mark || !elasticlunr) {
+        return;
+    }
+    
+    var searchbar = document.getElementById('searchbar'),
+        searchbar_outer = document.getElementById('searchbar-outer'),
+        searchresults = document.getElementById('searchresults'),
+        searchresults_outer = document.getElementById('searchresults-outer'),
+        searchresults_header = document.getElementById('searchresults-header'),
+        searchicon = document.getElementById('search-toggle'),
+        content = document.getElementById('content'),
+
+        searchindex = null,
+        resultsoptions = {
+            teaser_word_count: 30,
+            limit_results: 30,
+        },
+        searchoptions = {
+            bool: "AND",
+            expand: true,
+            fields: {
+                title: {boost: 1},
+                body: {boost: 1},
+                breadcrumbs: {boost: 0}
+            }
+        },
+        mark_exclude = [],
+        marker = new Mark(content),
+        current_searchterm = "",
+        URL_SEARCH_PARAM = 'search',
+        URL_MARK_PARAM = 'highlight',
+        teaser_count = 0,
+
+        SEARCH_HOTKEY_KEYCODE = 83,
+        ESCAPE_KEYCODE = 27,
+        DOWN_KEYCODE = 40,
+        UP_KEYCODE = 38,
+        SELECT_KEYCODE = 13;
+
+    function hasFocus() {
+        return searchbar === document.activeElement;
+    }
+
+    function removeChildren(elem) {
+        while (elem.firstChild) {
+            elem.removeChild(elem.firstChild);
+        }
+    }
+
+    // Helper to parse a url into its building blocks.
+    function parseURL(url) {
+        var a =  document.createElement('a');
+        a.href = url;
+        return {
+            source: url,
+            protocol: a.protocol.replace(':',''),
+            host: a.hostname,
+            port: a.port,
+            params: (function(){
+                var ret = {};
+                var seg = a.search.replace(/^\?/,'').split('&');
+                var len = seg.length, i = 0, s;
+                for (;i<len;i++) {
+                    if (!seg[i]) { continue; }
+                    s = seg[i].split('=');
+                    ret[s[0]] = s[1];
+                }
+                return ret;
+            })(),
+            file: (a.pathname.match(/\/([^/?#]+)$/i) || [,''])[1],
+            hash: a.hash.replace('#',''),
+            path: a.pathname.replace(/^([^/])/,'/$1')
+        };
+    }
+    
+    // Helper to recreate a url string from its building blocks.
+    function renderURL(urlobject) {
+        var url = urlobject.protocol + "://" + urlobject.host;
+        if (urlobject.port != "") {
+            url += ":" + urlobject.port;
+        }
+        url += urlobject.path;
+        var joiner = "?";
+        for(var prop in urlobject.params) {
+            if(urlobject.params.hasOwnProperty(prop)) {
+                url += joiner + prop + "=" + urlobject.params[prop];
+                joiner = "&";
+            }
+        }
+        if (urlobject.hash != "") {
+            url += "#" + urlobject.hash;
+        }
+        return url;
+    }
+    
+    // Helper to escape html special chars for displaying the teasers
+    var escapeHTML = (function() {
+        var MAP = {
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&#34;',
+            "'": '&#39;'
+        };
+        var repl = function(c) { return MAP[c]; };
+        return function(s) {
+            return s.replace(/[&<>'"]/g, repl);
+        };
+    })();
+    
+    function formatSearchMetric(count, searchterm) {
+        if (count == 1) {
+            return count + " search result for '" + searchterm + "':";
+        } else if (count == 0) {
+            return "No search results for '" + searchterm + "'.";
+        } else {
+            return count + " search results for '" + searchterm + "':";
+        }
+    }
+    
+    function formatSearchResult(result, searchterms) {
+        var teaser = makeTeaser(escapeHTML(result.doc.body), searchterms);
+        teaser_count++;
+
+        // The ?URL_MARK_PARAM= parameter belongs inbetween the page and the #heading-anchor
+        var url = result.ref.split("#");
+        if (url.length == 1) { // no anchor found
+            url.push("");
+        }
+
+        return '<a href="' + url[0] + '?' + URL_MARK_PARAM + '=' + searchterms + '#' + url[1]
+            + '" aria-details="teaser_' + teaser_count + '">' + result.doc.breadcrumbs + '</a>'
+            + '<span class="teaser" id="teaser_' + teaser_count + '" aria-label="Search Result Teaser">' 
+            + teaser + '</span>';
+    }
+    
+    function makeTeaser(body, searchterms) {
+        // The strategy is as follows:
+        // First, assign a value to each word in the document:
+        //  Words that correspond to search terms (stemmer aware): 40
+        //  Normal words: 2
+        //  First word in a sentence: 8
+        // Then use a sliding window with a constant number of words and count the
+        // sum of the values of the words within the window. Then use the window that got the
+        // maximum sum. If there are multiple maximas, then get the last one.
+        // Enclose the terms in <em>.
+        var stemmed_searchterms = searchterms.map(function(w) {
+            return elasticlunr.stemmer(w.toLowerCase());
+        });
+        var searchterm_weight = 40;
+        var weighted = []; // contains elements of ["word", weight, index_in_document]
+        // split in sentences, then words
+        var sentences = body.toLowerCase().split('. ');
+        var index = 0;
+        var value = 0;
+        var searchterm_found = false;
+        for (var sentenceindex in sentences) {
+            var words = sentences[sentenceindex].split(' ');
+            value = 8;
+            for (var wordindex in words) {
+                var word = words[wordindex];
+                if (word.length > 0) {
+                    for (var searchtermindex in stemmed_searchterms) {
+                        if (elasticlunr.stemmer(word).startsWith(stemmed_searchterms[searchtermindex])) {
+                            value = searchterm_weight;
+                            searchterm_found = true;
+                        }
+                    };
+                    weighted.push([word, value, index]);
+                    value = 2;
+                }
+                index += word.length;
+                index += 1; // ' ' or '.' if last word in sentence
+            };
+            index += 1; // because we split at a two-char boundary '. '
+        };
+
+        if (weighted.length == 0) {
+            return body;
+        }
+
+        var window_weight = [];
+        var window_size = Math.min(weighted.length, resultsoptions.teaser_word_count);
+
+        var cur_sum = 0;
+        for (var wordindex = 0; wordindex < window_size; wordindex++) {
+            cur_sum += weighted[wordindex][1];
+        };
+        window_weight.push(cur_sum);
+        for (var wordindex = 0; wordindex < weighted.length - window_size; wordindex++) {
+            cur_sum -= weighted[wordindex][1];
+            cur_sum += weighted[wordindex + window_size][1];
+            window_weight.push(cur_sum);
+        };
+
+        if (searchterm_found) {
+            var max_sum = 0;
+            var max_sum_window_index = 0;
+            // backwards
+            for (var i = window_weight.length - 1; i >= 0; i--) {
+                if (window_weight[i] > max_sum) {
+                    max_sum = window_weight[i];
+                    max_sum_window_index = i;
+                }
+            };
+        } else {
+            max_sum_window_index = 0;
+        }
+
+        // add <em/> around searchterms
+        var teaser_split = [];
+        var index = weighted[max_sum_window_index][2];
+        for (var i = max_sum_window_index; i < max_sum_window_index+window_size; i++) {
+            var word = weighted[i];
+            if (index < word[2]) {
+                // missing text from index to start of `word`
+                teaser_split.push(body.substring(index, word[2]));
+                index = word[2];
+            }
+            if (word[1] == searchterm_weight) {
+                teaser_split.push("<em>")
+            }
+            index = word[2] + word[0].length;
+            teaser_split.push(body.substring(word[2], index));
+            if (word[1] == searchterm_weight) {
+                teaser_split.push("</em>")
+            }
+        };
+
+        return teaser_split.join('');
+    }
+
+    function init() {
+        resultsoptions = window.search.resultsoptions;
+        searchoptions = window.search.searchoptions;
+        searchindex = elasticlunr.Index.load(window.search.index);
+
+        // Set up events
+        searchicon.addEventListener('click', function(e) { searchIconClickHandler(); }, false);
+        searchbar.addEventListener('keyup', function(e) { searchbarKeyUpHandler(); }, false);
+        document.addEventListener('keydown', function (e) { globalKeyHandler(e); }, false);
+        // If the user uses the browser buttons, do the same as if a reload happened
+        window.onpopstate = function(e) { doSearchOrMarkFromUrl(); };
+
+        // If reloaded, do the search or mark again, depending on the current url parameters
+        doSearchOrMarkFromUrl();
+    }
+    
+    function unfocusSearchbar() {
+        // hacky, but just focusing a div only works once
+        var tmp = document.createElement('input');
+        tmp.setAttribute('style', 'position: absolute; opacity: 0;');
+        searchicon.appendChild(tmp);
+        tmp.focus();
+        tmp.remove();
+    }
+    
+    // On reload or browser history backwards/forwards events, parse the url and do search or mark
+    function doSearchOrMarkFromUrl() {
+        // Check current URL for search request
+        var url = parseURL(window.location.href);
+        if (url.params.hasOwnProperty(URL_SEARCH_PARAM)
+            && url.params[URL_SEARCH_PARAM] != "") {
+            showSearch(true);
+            searchbar.value = decodeURIComponent(
+                (url.params[URL_SEARCH_PARAM]+'').replace(/\+/g, '%20'));
+            searchbarKeyUpHandler(); // -> doSearch()
+        } else {
+            showSearch(false);
+        }
+
+        if (url.params.hasOwnProperty(URL_MARK_PARAM)) {
+            var words = url.params[URL_MARK_PARAM].split(' ');
+            marker.mark(words, {
+                exclude: mark_exclude
+            });
+
+            var markers = document.querySelectorAll("mark");
+            function hide() {
+                for (var i = 0; i < markers.length; i++) {
+                    markers[i].classList.add("fade-out");
+                    window.setTimeout(function(e) { marker.unmark(); }, 300);
+                }
+            }
+            for (var i = 0; i < markers.length; i++) {
+                markers[i].addEventListener('click', hide);
+            }
+        }
+    }
+    
+    // Eventhandler for keyevents on `document`
+    function globalKeyHandler(e) {
+        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+
+        if (e.keyCode == ESCAPE_KEYCODE) {
+            e.preventDefault();
+            searchbar.classList.remove("active");
+            setSearchUrlParameters("",
+                (searchbar.value.trim() != "") ? "push" : "replace");
+            if (hasFocus()) {
+                unfocusSearchbar();
+            }
+            showSearch(false);
+            marker.unmark();
+            return;
+        }
+        if (!hasFocus() && e.keyCode == SEARCH_HOTKEY_KEYCODE) {
+            e.preventDefault();
+            showSearch(true);
+            window.scrollTo(0, 0);
+            searchbar.focus();
+            return;
+        }
+        if (hasFocus() && e.keyCode == DOWN_KEYCODE) {
+            e.preventDefault();
+            unfocusSearchbar();
+            searchresults.children('li').first().classList.add("focus");
+            return;
+        }
+        if (!hasFocus() && (e.keyCode == DOWN_KEYCODE
+                            || e.keyCode == UP_KEYCODE
+                            || e.keyCode == SELECT_KEYCODE)) {
+            // not `:focus` because browser does annoying scrolling
+            var current_focus = search.searchresults.find("li.focus");
+            if (current_focus.length == 0) return;
+            e.preventDefault();
+            if (e.keyCode == DOWN_KEYCODE) {
+                var next = current_focus.next()
+                if (next.length > 0) {
+                    current_focus.classList.remove("focus");
+                    next.classList.add("focus");
+                }
+            } else if (e.keyCode == UP_KEYCODE) {
+                current_focus.classList.remove("focus");
+                var prev = current_focus.prev();
+                if (prev.length == 0) {
+                    searchbar.focus();
+                } else {
+                    prev.classList.add("focus");
+                }
+            } else {
+                window.location = current_focus.children('a').attr('href');
+            }
+        }
+    }
+    
+    function showSearch(yes) {
+        if (yes) {
+            searchbar_outer.style.display = 'block';
+            content.style.display = 'none';
+            searchicon.setAttribute('aria-expanded', 'true');
+        } else {
+            content.style.display = 'block';
+            searchbar_outer.style.display = 'none';
+            searchresults_outer.style.display = 'none';
+            searchbar.value = '';
+            removeChildren(searchresults);
+            searchicon.setAttribute('aria-expanded', 'false');
+        }
+    }
+
+    function showResults(yes) {
+        if (yes) {
+            searchbar_outer.style.display = 'block';
+            content.style.display = 'none';
+            searchresults_outer.style.display = 'block';
+        } else {
+            content.style.display = 'block';
+            searchresults_outer.style.display = 'none';
+        }
+    }
+
+    // Eventhandler for search icon
+    function searchIconClickHandler() {
+        if (searchbar_outer.style.display === 'block') {
+            showSearch(false);
+        } else {
+            showSearch(true);
+            window.scrollTo(0, 0);
+            searchbar.focus();
+        }
+    }
+    
+    // Eventhandler for keyevents while the searchbar is focused
+    function searchbarKeyUpHandler() {
+        var searchterm = searchbar.value.trim();
+        if (searchterm != "") {
+            searchbar.classList.add("active");
+            doSearch(searchterm);
+        } else {
+            searchbar.classList.remove("active");
+            showResults(false);
+            removeChildren(searchresults);
+        }
+
+        setSearchUrlParameters(searchterm, "push_if_new_search_else_replace");
+
+        // Remove marks
+        marker.unmark();
+    }
+    
+    // Update current url with ?URL_SEARCH_PARAM= parameter, remove ?URL_MARK_PARAM and #heading-anchor .
+    // `action` can be one of "push", "replace", "push_if_new_search_else_replace"
+    // and replaces or pushes a new browser history item.
+    // "push_if_new_search_else_replace" pushes if there is no `?URL_SEARCH_PARAM=abc` yet.
+    function setSearchUrlParameters(searchterm, action) {
+        var url = parseURL(window.location.href);
+        var first_search = ! url.params.hasOwnProperty(URL_SEARCH_PARAM);
+        if (searchterm != "" || action == "push_if_new_search_else_replace") {
+            url.params[URL_SEARCH_PARAM] = searchterm;
+            delete url.params[URL_MARK_PARAM];
+            url.hash = "";
+        } else {
+            delete url.params[URL_SEARCH_PARAM];
+        }
+        // A new search will also add a new history item, so the user can go back
+        // to the page prior to searching. A updated search term will only replace
+        // the url.
+        if (action == "push" || (action == "push_if_new_search_else_replace" && first_search) ) {
+            history.pushState({}, document.title, renderURL(url));
+        } else if (action == "replace" || (action == "push_if_new_search_else_replace" && !first_search) ) {
+            history.replaceState({}, document.title, renderURL(url));
+        }
+    }
+    
+    function doSearch(searchterm) {
+
+        // Don't search the same twice
+        if (current_searchterm == searchterm) { return; }
+        else { current_searchterm = searchterm; }
+
+        if (searchindex == null) { return; }
+
+        // Do the actual search
+        var results = searchindex.search(searchterm, searchoptions);
+        var resultcount = Math.min(results.length, resultsoptions.limit_results);
+
+        // Display search metrics
+        searchresults_header.innerText = formatSearchMetric(resultcount, searchterm);
+
+        // Clear and insert results
+        var searchterms  = searchterm.split(' ');
+        removeChildren(searchresults);
+        for(var i = 0; i < resultcount ; i++){
+            var resultElem = document.createElement('li');
+            resultElem.innerHTML = formatSearchResult(results[i], searchterms);
+            searchresults.appendChild(resultElem);
+        }
+
+        // Display results
+        showResults(true);
+    }
+
+    init();
+    // Exported functions
+    search.hasFocus = hasFocus;
+})(window.search);

src/theme/stylus/book.styl

@@ -9,3 +9,4 @@
 @import 'themes'
 @import 'print'
 @import 'tooltip'
+@import 'searchbar'

src/theme/stylus/general.styl

@@ -35,6 +35,16 @@ h4, h5 { margin-top: 2em }
 
 .header + .header h3, .header + .header h4, .header + .header h5 { margin-top: 1em }
 
+a.header:target h1:before,
+a.header:target h2:before,
+a.header:target h3:before,
+a.header:target h4:before {
+    display: inline-block;
+    content: "»";
+    margin-left: -30px;
+    width: 30px;
+}
+
 table {
     margin: 0 auto;
     border-collapse: collapse;
@@ -48,3 +58,15 @@ table {
       td { font-weight: 700; }
     }
 }
+
+:not(.footnote-definition) + .footnote-definition,
+.footnote-definition + :not(.footnote-definition) {
+    margin-top: 2em;
+}
+
+.footnote-definition {
+    font-size: 0.9em;
+    margin: 0.5em 0;
+
+    p { display: inline; }
+}

src/theme/stylus/menu.styl

@@ -38,4 +38,5 @@ html:not(.sidebar-visible) #menu-bar:not(:hover).folded > #menu-bar-sticky-conta
     white-space: nowrap
     overflow: hidden
     text-overflow: ellipsis
+    cursor: pointer;
 }

src/theme/stylus/page.styl

@@ -2,20 +2,18 @@
 
 .page-wrapper {
     box-sizing: border-box
+    left: 0
+    position: absolute
+    right: 0
+    top: 0
+    bottom: 0
 
     // Animation: slide away
-    transition: padding-left 0.5s, margin-left 0.5s
+    transition: padding-left 0.5s, margin-left 0.5s, left 0.5s
 }
 
 .sidebar-visible .page-wrapper {
-    padding-left: $sidebar-width
-}
-
-@media only screen and (max-width: $page-plus-sidebar-width - 1) {
-    .sidebar-visible .page-wrapper {
-        padding-left: 0
-        margin-left: $sidebar-width
-    }
+    left: $sidebar-width
 }
 
 .page {
@@ -24,11 +22,21 @@
 }
 
 .content {
-    margin-left: auto
-    margin-right: auto
-    max-width: $content-max-width
+    position: relative
+    top: 0
+    bottom: 0
+    overflow-y: auto
+    right: 0
+    left: 0
+    padding: 0 15px
     padding-bottom: 50px
 
+    main {
+        margin-left: auto
+        margin-right: auto
+        max-width: $content-max-width
+    }
+
     a {
         text-decoration: none;
         &:hover { text-decoration: underline; }
@@ -36,3 +44,8 @@
 
     img { max-width: 100%; }
 }
+
+.sidebar-visible .content {
+    position: absolute
+    top: 52px
+}

src/theme/stylus/searchbar.styl

@@ -0,0 +1,67 @@
+@require 'variables'
+
+#searchresults a {
+    text-decoration: none;
+}
+
+mark {
+    border-radius: 2px;
+    padding: 0 3px 1px 3px;
+    margin: 0 -3px -1px -3px;
+    transition: background-color 300ms linear;
+}
+
+.fade-out {
+    background-color: rgba(0,0,0,0) !important
+}
+
+.searchbar-outer {
+    display: none;
+    margin-left: auto;
+    margin-right: auto;
+    max-width: $content-max-width;
+}
+
+#searchbar {
+    display: block;
+    width: 100%;
+    margin: 5px auto 0px auto;
+    padding: 10px 16px;
+    transition: box-shadow 300ms ease-in-out;
+}
+
+.searchresults-header {
+    font-weight: bold;
+    font-size: 1em;
+    padding: 18px 0 0 5px;
+}
+
+.searchresults-outer {
+    display: none;
+    margin-left: auto;
+    margin-right: auto;
+    max-width: $content-max-width;
+}
+
+ul#searchresults {
+    list-style: none;
+    padding-left: 20px;
+
+    li {
+        margin: 10px 0px;
+        padding: 2px;
+        border-radius: 2px;
+    }
+
+    span.teaser {
+        display: block;
+        clear: both;
+        margin: 5px 0 0 20px;
+        font-size: 0.8em;
+    }
+
+    span.teaser em {
+        font-weight: bold;
+        font-style: normal;
+    }
+}

src/theme/stylus/sidebar.styl

@@ -11,6 +11,7 @@
     font-size: 0.875em
     box-sizing: border-box
     -webkit-overflow-scrolling: touch
+    overscroll-behavior-y: contain;
 
     // Animation: slide away
     transition: transform 0.5s
@@ -31,16 +32,18 @@
 
     li a {
         display: block;
-        padding: 5px 0
+        padding: 0
         text-decoration: none
 
+        @media (-moz-touch-enabled: 1), (pointer: coarse) { padding: 5px 0; }
         &:hover { text-decoration: none }
     }
 
     .spacer {
         width: 100%
         height: 3px
-        margin: 10px 0px
+        margin: 5px 0px
+        @media (-moz-touch-enabled: 1), (pointer: coarse) { margin: 10px 0; }
     }
 }
 

src/theme/stylus/themes/ayu.styl

@@ -9,6 +9,8 @@ $sidebar-non-existant = #5c6773
 $sidebar-active = #ffb454
 $sidebar-spacer = #2d334f
 
+$scrollbar = $sidebar-fg
+
 $icons = #737480
 $icons-hover = #b7b9cc
 
@@ -27,4 +29,13 @@ $table-border-color = lighten($bg, 5%)
 $table-header-bg = lighten($bg, 20%)
 $table-alternate-bg = lighten($bg, 3%)
 
+$searchbar-border-color = #848484
+$searchbar-bg = #424242
+$searchbar-fg = #fff
+$searchbar-shadow-color = #d4c89f
+$searchresults-header-fg = #666
+$searchresults-border-color = #888
+$searchresults-li-bg = #252932
+$search-mark-bg = #e3b171
+
 @import 'base'

src/theme/stylus/themes/base.styl

@@ -32,6 +32,14 @@
     .sidebar {
         background-color: $sidebar-bg
         color: $sidebar-fg
+
+        &::-webkit-scrollbar {
+            background: $sidebar-bg;
+        }
+
+        &::-webkit-scrollbar-thumb {
+            background: $scrollbar;
+        }
     }
 
     .chapter li {
@@ -76,7 +84,10 @@
         background-color: $sidebar-bg
     }
 
-    .content a:link, a:visited, a > .hljs {
+    #searchresults a,
+    .content a:link,
+    a:visited,
+    a > .hljs {
         color: $links
     }
 
@@ -172,4 +183,40 @@
             margin: 0;
         }
     }
+
+    ::-webkit-scrollbar {
+        background: $bg;
+    }
+
+    ::-webkit-scrollbar-thumb {
+        background: $scrollbar;
+    }
+
+    /* Search */
+    #searchbar {
+        border: 1px solid $searchbar-border-color;
+        border-radius: 3px;
+        background-color: $searchbar-bg;
+        color: $searchbar-fg
+
+        &:focus, &.active {
+            box-shadow: 0 0 3px $searchbar-shadow-color;
+        }
+    }
+
+    .searchresults-header {
+        color: $searchresults-header-fg;
+    }
+
+    .searchresults-outer {
+        border-bottom: 1px dashed $searchresults-border-color;
+    }
+
+    ul#searchresults li.focus {
+        background-color: $searchresults-li-bg;
+    }
+
+    mark {
+        background-color: $search-mark-bg;
+    }
 }

src/theme/stylus/themes/coal.styl

@@ -9,6 +9,8 @@ $sidebar-non-existant = #505254
 $sidebar-active = #3473ad
 $sidebar-spacer = #393939
 
+$scrollbar = $sidebar-fg
+
 $icons = #43484d
 $icons-hover = #b3c0cc
 
@@ -27,4 +29,13 @@ $table-border-color = lighten($bg, 5%)
 $table-header-bg = lighten($bg, 20%)
 $table-alternate-bg = lighten($bg, 3%)
 
+$searchbar-border-color = #aaa
+$searchbar-bg = #b7b7b7
+$searchbar-fg = #000
+$searchbar-shadow-color = #aaa
+$searchresults-header-fg = #666
+$searchresults-border-color = #98a3ad
+$searchresults-li-bg = #2b2b2f
+$search-mark-bg = #355c7d
+
 @import 'base'

src/theme/stylus/themes/light.styl

@@ -9,12 +9,14 @@ $sidebar-non-existant = #aaaaaa
 $sidebar-active = #008cff
 $sidebar-spacer = #f4f4f4
 
+$scrollbar = #cccccc
+
 $icons = #cccccc
 $icons-hover = #333333
 
 $links = #4183c4
 
-$inline-code-color = #6e6b5e;
+$inline-code-color = #6e6b5e
 
 $theme-popup-bg = #fafafa
 $theme-popup-border = #cccccc
@@ -27,4 +29,13 @@ $table-border-color = darken($bg, 5%)
 $table-header-bg = darken($bg, 20%)
 $table-alternate-bg = darken($bg, 3%)
 
+$searchbar-border-color = #aaa
+$searchbar-bg = #fafafa
+$searchbar-fg = #000
+$searchbar-shadow-color = #aaa
+$searchresults-header-fg = #666
+$searchresults-border-color = #888
+$searchresults-li-bg = #e4f2fe
+$search-mark-bg = #a2cff5
+
 @import 'base'

src/theme/stylus/themes/navy.styl

@@ -9,6 +9,8 @@ $sidebar-non-existant = #505274
 $sidebar-active = #2b79a2
 $sidebar-spacer = #2d334f
 
+$scrollbar = $sidebar-fg
+
 $icons = #737480
 $icons-hover = #b7b9cc
 
@@ -27,4 +29,13 @@ $table-border-color = lighten($bg, 5%)
 $table-header-bg = lighten($bg, 20%)
 $table-alternate-bg = lighten($bg, 3%)
 
+$searchbar-border-color = #aaa
+$searchbar-bg = #aeaec6
+$searchbar-fg = #000
+$searchbar-shadow-color = #aaa
+$searchresults-header-fg = #5f5f71
+$searchresults-border-color = #5c5c68
+$searchresults-li-bg = #242430
+$search-mark-bg = #a2cff5
+
 @import 'base'

src/theme/stylus/themes/rust.styl

@@ -9,6 +9,8 @@ $sidebar-non-existant = #505254
 $sidebar-active = #e69f67
 $sidebar-spacer = #45373a
 
+$scrollbar = $sidebar-fg
+
 $icons = #737480
 $icons-hover = #262625
 
@@ -27,4 +29,13 @@ $table-border-color = darken($bg, 5%)
 $table-header-bg = #b3a497
 $table-alternate-bg = darken($bg, 3%)
 
+$searchbar-border-color = #aaa
+$searchbar-bg = #fafafa
+$searchbar-fg = #000
+$searchbar-shadow-color = #aaa
+$searchresults-header-fg = #666
+$searchresults-border-color = #888
+$searchresults-li-bg = #dec2a2
+$search-mark-bg = #e69f67
+
 @import 'base'

src/utils/fs.rs

@@ -1,7 +1,7 @@
-use std::path::{Component, Path, PathBuf};
 use errors::*;
-use std::io::Read;
 use std::fs::{self, File};
+use std::io::{Read, Write};
+use std::path::{Component, Path, PathBuf};
 
 /// Takes a path to a file and try to read the file into a String
 pub fn file_to_string<P: AsRef<Path>>(path: P) -> Result<String> {
@@ -16,6 +16,27 @@ pub fn file_to_string<P: AsRef<Path>>(path: P) -> Result<String> {
     Ok(content)
 }
 
+/// Naively replaces any path seperator with a forward-slash '/'
+pub fn normalize_path(path: &str) -> String {
+    use std::path::is_separator;
+    path.chars()
+        .map(|ch| if is_separator(ch) { '/' } else { ch })
+        .collect::<String>()
+}
+
+/// Write the given data to a file, creating it first if necessary
+pub fn write_file<P: AsRef<Path>>(
+    build_dir: &Path,
+    filename: P,
+    content: &[u8],
+) -> Result<()> {
+    let path = build_dir.join(filename);
+
+    create_file(&path)?
+        .write_all(content)
+        .map_err(|e| e.into())
+}
+
 /// Takes a path and returns a path containing just enough `../` to point to
 /// the root of the given path.
 ///
@@ -38,7 +59,6 @@ pub fn file_to_string<P: AsRef<Path>>(path: P) -> Result<String> {
 /// it doesn't return the correct path.
 /// Consider [submitting a new issue](https://github.com/rust-lang-nursery/mdBook/issues)
 /// or a [pull-request](https://github.com/rust-lang-nursery/mdBook/pulls) to improve it.
-
 pub fn path_to_root<P: Into<PathBuf>>(path: P) -> String {
     debug!("path_to_root");
     // Remove filename and add "../" for every directory
@@ -61,7 +81,6 @@ pub fn path_to_root<P: Into<PathBuf>>(path: P) -> String {
 /// This function creates a file and returns it. But before creating the file
 /// it checks every directory in the path to see if it exists,
 /// and if it does not it will be created.
-
 pub fn create_file(path: &Path) -> Result<File> {
     debug!("Creating {}", path.display());
 
@@ -76,7 +95,6 @@ pub fn create_file(path: &Path) -> Result<File> {
 }
 
 /// Removes all the content of a directory but not the directory itself
-
 pub fn remove_dir_content(dir: &Path) -> Result<()> {
     for item in fs::read_dir(dir)? {
         if let Ok(item) = item {
@@ -93,7 +111,6 @@ pub fn remove_dir_content(dir: &Path) -> Result<()> {
 
 /// Copies all files of a directory to another one except the files
 /// with the extensions given in the `ext_blacklist` array
-
 pub fn copy_files_except_ext(
     from: &Path,
     to: &Path,
@@ -176,14 +193,14 @@ pub fn copy_files_except_ext(
 
 #[cfg(test)]
 mod tests {
-    extern crate tempdir;
+    extern crate tempfile;
 
     use super::copy_files_except_ext;
     use std::fs;
 
     #[test]
     fn copy_files_except_ext_test() {
-        let tmp = match tempdir::TempDir::new("") {
+        let tmp = match tempfile::TempDir::new() {
             Ok(t) => t,
             Err(_) => panic!("Could not create a temp dir"),
         };

src/utils/mod.rs

@@ -3,13 +3,71 @@
 pub mod fs;
 mod string;
 use errors::Error;
+use regex::Regex;
 
 use pulldown_cmark::{html, Event, Options, Parser, Tag, OPTION_ENABLE_FOOTNOTES,
                      OPTION_ENABLE_TABLES};
+
 use std::borrow::Cow;
 
 pub use self::string::{RangeArgument, take_lines};
 
+/// Replaces multiple consecutive whitespace characters with a single space character.
+pub fn collapse_whitespace<'a>(text: &'a str) -> Cow<'a, str> {
+    lazy_static! {
+        static ref RE: Regex = Regex::new(r"\s\s+").unwrap();
+    }
+    RE.replace_all(text, " ")
+}
+
+/// Convert the given string to a valid HTML element ID
+pub fn normalize_id(content: &str) -> String {
+    let mut ret = content
+        .chars()
+        .filter_map(|ch| {
+            if ch.is_alphanumeric() || ch == '_' || ch == '-' {
+                Some(ch.to_ascii_lowercase())
+            } else if ch.is_whitespace() {
+                Some('-')
+            } else {
+                None
+            }
+        })
+        .collect::<String>();
+    // Ensure that the first character is [A-Za-z]
+    if ret.chars().next().map_or(false, |c| !c.is_ascii_alphabetic()) {
+        ret.insert(0, 'a');
+    }
+    ret
+}
+
+/// Generate an ID for use with anchors which is derived from a "normalised"
+/// string.
+pub fn id_from_content(content: &str) -> String {
+    let mut content = content.to_string();
+
+    // Skip any tags or html-encoded stuff
+    const REPL_SUB: &[&str] = &["<em>",
+                                "</em>",
+                                "<code>",
+                                "</code>",
+                                "<strong>",
+                                "</strong>",
+                                "&lt;",
+                                "&gt;",
+                                "&amp;",
+                                "&#39;",
+                                "&quot;"];
+    for sub in REPL_SUB {
+        content = content.replace(sub, "");
+    }
+
+    // Remove spaces and hashes indicating a header
+    let trimmed = content.trim().trim_left_matches('#').trim();
+
+    normalize_id(trimmed)
+}
+
 /// Wrapper around the pulldown-cmark parser for rendering markdown to HTML.
 pub fn render_markdown(text: &str, curly_quotes: bool) -> String {
     let mut s = String::with_capacity(text.len() * 3 / 2);
@@ -212,6 +270,29 @@ more text with spaces
         }
     }
 
+    mod html_munging {
+        use super::super::{id_from_content, normalize_id};
+
+        #[test]
+        fn it_generates_anchors() {
+            assert_eq!(id_from_content("## `--passes`: add more rustdoc passes"),
+                    "a--passes-add-more-rustdoc-passes");
+            assert_eq!(id_from_content("## Method-call expressions"),
+                    "method-call-expressions");
+        }
+
+        #[test]
+        fn it_normalizes_ids() {
+            assert_eq!(normalize_id("`--passes`: add more rustdoc passes"),
+                    "a--passes-add-more-rustdoc-passes");
+            assert_eq!(normalize_id("Method-call 🐙 expressions \u{1f47c}"),
+                    "method-call--expressions-");
+            assert_eq!(normalize_id("_-_12345"), "a_-_12345");
+            assert_eq!(normalize_id("12345"), "a12345");
+            assert_eq!(normalize_id(""), "");
+        }
+    }
+
     mod convert_quotes_to_curly {
         use super::super::convert_quotes_to_curly;
 

src/utils/string.rs

@@ -50,7 +50,7 @@ pub fn take_lines<R: RangeArgument<usize>>(s: &str, range: R) -> String {
     let start = *range.start().unwrap_or(&0);
     let mut lines = s.lines().skip(start);
     match range.end() {
-        Some(&end) => lines.take(end).join("\n"),
+        Some(&end) => lines.take(end.checked_sub(start).unwrap_or(0)).join("\n"),
         None => lines.join("\n"),
     }
 }
@@ -62,9 +62,12 @@ mod tests {
     #[test]
     fn take_lines_test() {
         let s = "Lorem\nipsum\ndolor\nsit\namet";
-        assert_eq!(take_lines(s, 0..3), "Lorem\nipsum\ndolor");
+        assert_eq!(take_lines(s, 1..3), "ipsum\ndolor");
         assert_eq!(take_lines(s, 3..), "sit\namet");
         assert_eq!(take_lines(s, ..3), "Lorem\nipsum\ndolor");
         assert_eq!(take_lines(s, ..), s);
+        // corner cases
+        assert_eq!(take_lines(s, 4..3), "");
+        assert_eq!(take_lines(s, ..100), s);
     }
 }

tests/alternate_backends.rs

@@ -1,14 +1,13 @@
 //! Integration tests to make sure alternate backends work.
 
 extern crate mdbook;
-extern crate tempdir;
+extern crate tempfile;
 
-use std::fs::File;
+#[cfg(not(windows))]
 use std::path::Path;
-use tempdir::TempDir;
+use tempfile::{TempDir, Builder as TempFileBuilder};
 use mdbook::config::Config;
 use mdbook::MDBook;
-use mdbook::renderer::RenderContext;
 
 #[test]
 fn passing_alternate_backend() {
@@ -24,6 +23,13 @@ fn failing_alternate_backend() {
     md.build().unwrap_err();
 }
 
+#[test]
+fn missing_backends_arent_fatal() {
+    let (md, _temp) = dummy_book_with_backend("missing", "trduyvbhijnorgevfuhn");
+
+    assert!(md.build().is_ok());
+}
+
 #[test]
 fn alternate_backend_with_arguments() {
     let (md, _temp) = dummy_book_with_backend("arguments", "echo Hello World!");
@@ -32,6 +38,7 @@ fn alternate_backend_with_arguments() {
 }
 
 /// Get a command which will pipe `stdin` to the provided file.
+#[cfg(not(windows))]
 fn tee_command<P: AsRef<Path>>(out_file: P) -> String {
     let out_file = out_file.as_ref();
 
@@ -45,7 +52,10 @@ fn tee_command<P: AsRef<Path>>(out_file: P) -> String {
 #[test]
 #[cfg(not(windows))]
 fn backends_receive_render_context_via_stdin() {
-    let temp = TempDir::new("output").unwrap();
+    use std::fs::File;
+    use mdbook::renderer::RenderContext;
+
+    let temp = TempFileBuilder::new().prefix("output").tempdir().unwrap();
     let out_file = temp.path().join("out.txt");
     let cmd = tee_command(&out_file);
 
@@ -60,7 +70,7 @@ fn backends_receive_render_context_via_stdin() {
 }
 
 fn dummy_book_with_backend(name: &str, command: &str) -> (MDBook, TempDir) {
-    let temp = TempDir::new("mdbook").unwrap();
+    let temp = TempFileBuilder::new().prefix("mdbook").tempdir().unwrap();
 
     let mut config = Config::default();
     config

tests/dummy_book/mod.rs

@@ -4,7 +4,7 @@
 // Not all features are used in all test crates, so...
 #![allow(dead_code, unused_variables, unused_imports, unused_extern_crates)]
 extern crate mdbook;
-extern crate tempdir;
+extern crate tempfile;
 extern crate walkdir;
 
 use std::path::Path;
@@ -15,7 +15,7 @@ use mdbook::utils::fs::file_to_string;
 
 // The funny `self::` here is because we've got an `extern crate ...` and are
 // in a submodule
-use self::tempdir::TempDir;
+use self::tempfile::{TempDir, Builder as TempFileBuilder};
 use self::mdbook::MDBook;
 use self::walkdir::WalkDir;
 
@@ -47,7 +47,7 @@ impl DummyBook {
 
     /// Write a book to a temporary directory using the provided settings.
     pub fn build(&self) -> Result<TempDir> {
-        let temp = TempDir::new("dummy_book").chain_err(|| "Unable to create temp directory")?;
+        let temp = TempFileBuilder::new().prefix("dummy_book").tempdir().chain_err(|| "Unable to create temp directory")?;
 
         let dummy_book_root = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/dummy_book");
         recursive_copy(&dummy_book_root, temp.path()).chain_err(|| {
@@ -128,11 +128,11 @@ fn recursive_copy<A: AsRef<Path>, B: AsRef<Path>>(from: A, to: B) -> Result<()>
 }
 
 pub fn new_copy_of_example_book() -> Result<TempDir> {
-    let temp = TempDir::new("book-example")?;
+    let temp = TempFileBuilder::new().prefix("book-example").tempdir()?;
     
     let book_example = Path::new(env!("CARGO_MANIFEST_DIR")).join("book-example");
 
     recursive_copy(book_example, temp.path())?;
 
     Ok(temp)
-}
+}

tests/dummy_book/src/conclusion.md

@@ -1 +1,20 @@
-# Conclusion
+# Conclusion
+
+<p>
+<!--secret secret-->
+I put &lt;HTML&gt; in here!<br/>
+</p>
+<script type="text/javascript" >
+// I probably shouldn't do this
+if (3 < 5 > 10)
+{
+    alert("The sky is falling!");
+}
+</script >
+<style >
+/*
+css looks, like this {
+    foo: < 3 <bar >
+}
+*/
+</style>

tests/init.rs

@@ -1,11 +1,11 @@
 extern crate mdbook;
-extern crate tempdir;
+extern crate tempfile;
 
 use std::path::PathBuf;
 use std::fs;
 use mdbook::MDBook;
 use mdbook::config::Config;
-use tempdir::TempDir;
+use tempfile::Builder as TempFileBuilder;
 
 
 /// Run `mdbook init` in an empty directory and make sure the default files
@@ -14,7 +14,7 @@ use tempdir::TempDir;
 fn base_mdbook_init_should_create_default_content() {
     let created_files = vec!["book", "src", "src/SUMMARY.md", "src/chapter_1.md"];
 
-    let temp = TempDir::new("mdbook").unwrap();
+    let temp = TempFileBuilder::new().prefix("mdbook").tempdir().unwrap();
     for file in &created_files {
         assert!(!temp.path().join(file).exists());
     }
@@ -34,7 +34,7 @@ fn base_mdbook_init_should_create_default_content() {
 fn run_mdbook_init_with_custom_book_and_src_locations() {
     let created_files = vec!["out", "in", "in/SUMMARY.md", "in/chapter_1.md"];
 
-    let temp = TempDir::new("mdbook").unwrap();
+    let temp = TempFileBuilder::new().prefix("mdbook").tempdir().unwrap();
     for file in &created_files {
         assert!(
             !temp.path().join(file).exists(),
@@ -61,7 +61,7 @@ fn run_mdbook_init_with_custom_book_and_src_locations() {
 
 #[test]
 fn book_toml_isnt_required() {
-    let temp = TempDir::new("mdbook").unwrap();
+    let temp = TempFileBuilder::new().prefix("mdbook").tempdir().unwrap();
     let md = MDBook::init(temp.path()).build().unwrap();
 
     let _ = fs::remove_file(temp.path().join("book.toml"));

tests/rendered_output.rs

@@ -2,7 +2,7 @@ extern crate mdbook;
 #[macro_use]
 extern crate pretty_assertions;
 extern crate select;
-extern crate tempdir;
+extern crate tempfile;
 extern crate walkdir;
 
 mod dummy_book;
@@ -16,7 +16,7 @@ use std::ffi::OsStr;
 use walkdir::{DirEntry, WalkDir};
 use select::document::Document;
 use select::predicate::{Class, Name, Predicate};
-use tempdir::TempDir;
+use tempfile::Builder as TempFileBuilder;
 use mdbook::errors::*;
 use mdbook::utils::fs::file_to_string;
 use mdbook::config::Config;
@@ -324,7 +324,7 @@ fn example_book_can_build() {
 
 #[test]
 fn book_with_a_reserved_filename_does_not_build() {
-    let tmp_dir = TempDir::new("mdBook").unwrap();
+    let tmp_dir = TempFileBuilder::new().prefix("mdBook").tempdir().unwrap();
     let src_path = tmp_dir.path().join("src");
     fs::create_dir(&src_path).unwrap();
 
@@ -339,3 +339,103 @@ fn book_with_a_reserved_filename_does_not_build() {
     let got = md.build();
     assert!(got.is_err());
 }
+
+#[cfg(feature = "search")]
+mod search {
+    extern crate serde_json;
+    use std::fs::File;
+    use std::path::Path;
+    use mdbook::utils::fs::file_to_string;
+    use mdbook::MDBook;
+    use dummy_book::DummyBook;
+
+    fn read_book_index(root: &Path) -> serde_json::Value {
+        let index = root.join("book/searchindex.js");
+        let index = file_to_string(index).unwrap();
+        let index = index.trim_left_matches("window.search = ");
+        let index = index.trim_right_matches(";");
+        serde_json::from_str(&index).unwrap()
+    }
+
+    #[test]
+    fn book_creates_reasonable_search_index() {
+        let temp = DummyBook::new().build().unwrap();
+        let md = MDBook::load(temp.path()).unwrap();
+        md.build().unwrap();
+
+        let index = read_book_index(temp.path());
+
+        let bodyidx = &index["index"]["index"]["body"]["root"];
+        let textidx = &bodyidx["t"]["e"]["x"]["t"];
+        assert_eq!(textidx["df"], 2);
+        assert_eq!(textidx["docs"]["first/index.html#first-chapter"]["tf"], 1.0);
+        assert_eq!(textidx["docs"]["intro.html#introduction"]["tf"], 1.0);
+
+        let docs = &index["index"]["documentStore"]["docs"];
+        assert_eq!(docs["first/index.html#first-chapter"]["body"], "more text.");
+        assert_eq!(docs["first/index.html#some-section"]["body"], "");
+        assert_eq!(
+            docs["first/includes.html#summary"]["body"],
+            "Introduction First Chapter Nested Chapter Includes Second Chapter Conclusion"
+        );
+        assert_eq!(
+            docs["first/includes.html#summary"]["breadcrumbs"],
+            "First Chapter » Summary"
+        );
+        assert_eq!(
+            docs["conclusion.html#conclusion"]["body"],
+            "I put <HTML> in here!"
+        );
+    }
+
+    // Setting this to `true` may cause issues with `cargo watch`,
+    // since it may not finish writing the fixture before the tests
+    // are run again.
+    const GENERATE_FIXTURE: bool = false;
+
+    fn get_fixture() -> serde_json::Value {
+        if GENERATE_FIXTURE {
+            let temp = DummyBook::new().build().unwrap();
+            let md = MDBook::load(temp.path()).unwrap();
+            md.build().unwrap();
+
+            let src = read_book_index(temp.path());
+
+            let dest = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/searchindex_fixture.json");
+            let dest = File::create(&dest).unwrap();
+            serde_json::to_writer_pretty(dest, &src).unwrap();
+
+            src
+        } else {
+            let json = include_str!("searchindex_fixture.json");
+            serde_json::from_str(json).expect("Unable to deserialize the fixture")
+        }
+    }
+
+    // So you've broken the test. If you changed dummy_book, it's probably
+    // safe to regenerate the fixture. If you haven't then make sure that the
+    // search index still works. Run `cargo run -- serve tests/dummy_book`
+    // and try some searches. Are you getting results? Do the teasers look OK?
+    // Are there new errors in the JS console?
+    //
+    // If you're pretty sure you haven't broken anything, change `GENERATE_FIXTURE`
+    // above to `true`, and run `cargo test` to generate a new fixture. Then
+    // change it back to `false`. Include the changed `searchindex_fixture.json` in your commit.
+    #[test]
+    fn search_index_hasnt_changed_accidentally() {
+        let temp = DummyBook::new().build().unwrap();
+        let md = MDBook::load(temp.path()).unwrap();
+        md.build().unwrap();
+
+        let book_index = read_book_index(temp.path());
+
+        let fixture_index = get_fixture();
+
+        // Uncomment this if you're okay with pretty-printing 32KB of JSON
+        //assert_eq!(fixture_index, book_index);
+
+        if book_index != fixture_index {
+            panic!("The search index has changed from the fixture");
+        }
+    }
+}