Override configuration using environment variables (#541)

* Added the ability to update config settings from env vars

* Added tests

* Documented that you can override configuration with environment
variables

* Refactored the config get() methods to use toml-query

* Made the `Updateable` trait more generic

Author: Michael-F-Bryan

Cargo.toml

@@ -34,6 +34,7 @@ tempdir = "0.3.4"
 itertools = "0.7.4"
 tempfile = "2.2.0"
 shlex = "0.1.1"
+toml-query = "0.6"
 
 # Watch feature
 notify = { version = "4.0", optional = true }

book-example/src/format/config.md

@@ -106,3 +106,43 @@ additional-js = ["custom.js"]
 editor = "./path/to/editor"
 editable = false
 ```
+
+
+## Environment Variables
+
+All configuration values van 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.
+
+Variables starting with `MDBOOK_` are used for configuration. The key is
+created by removing the `MDBOOK_` prefix and turning the resulting
+string into `kebab-case`. Double underscores (`__`) separate nested
+keys, while a single underscore (`_`) is replaced with a dash (`-`).
+
+For example:
+
+- `MDBOOK_foo` -> `foo`
+- `MDBOOK_FOO` -> `foo`
+- `MDBOOK_FOO__BAR` -> `foo.bar`
+- `MDBOOK_FOO_BAR` -> `foo-bar`
+- `MDBOOK_FOO_bar__baz` -> `foo-bar.baz`
+
+So by setting the `MDBOOK_BOOK__TITLE` environment variable you can
+override the book's title without needing to touch your `book.toml`.
+
+> **Note:** To facilitate setting more complex config items, the value
+> of an environment variable is first parsed as JSON, falling back to a
+> string if the parse fails.
+>
+> This means, if you so desired, you could override all book metadata
+> when building the book with something like
+>
+> ```text
+> $ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}"
+> $ mdbook build
+> ```
+
+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.

src/book/mod.rs

@@ -58,13 +58,15 @@ impl MDBook {
             warn!("\thttps://rust-lang-nursery.github.io/mdBook/format/config.html");
         }
 
-        let config = if config_location.exists() {
+        let mut config = if config_location.exists() {
             debug!("[*] Loading config from {}", config_location.display());
             Config::from_disk(&config_location)?
         } else {
             Config::default()
         };
 
+        config.update_from_env();
+
         if log_enabled!(::log::Level::Trace) {
             for line in format!("Config: {:#?}", config).lines() {
                 trace!("{}", line);