Merge pull request #2943 from ehuss/config-changelog

Add some more 0.5 Config API changes

CHANGELOG.md

@@ -1,15 +1,40 @@
 # Changelog
 
-## 0.5 Migration Guide
+## mdBook 0.5.0
+[v0.4.52...v0.5.0](https://github.com/rust-lang/mdBook/compare/v0.4.52...v0.5.0)
 
-During the pre-release phase of the 0.5 release, the documentation may be found at <https://rust-lang.github.io/mdBook/pre-release/>.
+The 0.5.0 release is the next major release of mdBook, containing over 130 PRs since 0.4.52! The primary focus for this release has been an evolution of the Rust APIs to make it easier to maintain, to evolve in a backwards-compatible fashion, to clean up some things that have accumulated over time, and to significantly improve the performance and compile-times.
+
+This release also includes many new features described below.
+
+We have prepared a [0.5 Migration Guide](#05-migration-guide) to help existing authors switch from 0.4.
+
+The final 0.5.0 release only contains the following changes since [0.5.0-beta.2](#mdbook-050-beta2):
+
+- Added error handling to environment config handling. This checks that environment variables starting with `MDBOOK_` are correctly specified instead of silently ignoring. This also fixed being able to replace entire top-level tables like `MDBOOK_OUTPUT`.
+  [#2942](https://github.com/rust-lang/mdBook/pull/2942)
+
+## 0.5 Migration Guide
 
 The 0.5 release contains several breaking changes from the 0.4 release. Preprocessors and renderers will need to be migrated to continue to work with this release. After updating your configuration, it is recommended to carefully compare and review how your book renders to ensure everything is working correctly.
 
 If you have overridden any of the theme files, you will likely need to update them to match the current version.
 
+See the entries below for [mdBook 0.5.0-alpha.1](#mdbook-050-alpha1), [mdBook 0.5.0-beta.1](#mdbook-050-beta1), and [mdBook 0.5.0-beta.2](#mdbook-050-beta2) for a more complete list of changes and fixes.
+
 The following is a summary of the changes that may require your attention when updating to 0.5:
 
+### Major additions
+
+- Added sidebar heading navigation. This includes the `output.html.sidebar-header-nav` option to disable it.
+  [#2822](https://github.com/rust-lang/mdBook/pull/2822)
+- Added support for definition lists. These are enabled by default, with the option `output.html.definition-lists` to disable it. See [docs](https://rust-lang.github.io/mdBook/format/markdown.html#definition-lists) for more.
+  [#2847](https://github.com/rust-lang/mdBook/pull/2847)
+- Added support for admonitions. These are enabled by default, with the option `output.html.admonitions` to disable it. See [docs](https://rust-lang.github.io/mdBook/format/markdown.html#admonitions) for more.
+  [#2851](https://github.com/rust-lang/mdBook/pull/2851)
+- Links on the print page now link to elements on the print page instead of linking out to the individual chapters.
+  [#2844](https://github.com/rust-lang/mdBook/pull/2844)
+
 ### Config changes
 
 - Unknown fields in config are now an error.
@@ -34,6 +59,10 @@ The following is a summary of the changes that may require your attention when u
   [#2775](https://github.com/rust-lang/mdBook/pull/2775)
 - Removed the very old legacy config support. Warnings have been displayed in previous versions on how to migrate.
   [#2783](https://github.com/rust-lang/mdBook/pull/2783)
+- Top-level config values set from the environment like `MDBOOK_BOOK` now *replace* the contents of the top-level table instead of merging into it.
+  [#2942](https://github.com/rust-lang/mdBook/pull/2942)
+- Invalid environment variables are now rejected. Previously unknown keys like `MDBOOK_FOO` would be ignored, or keys or invalid values inside objects like the `[book]` table would be ignored.
+  [#2942](https://github.com/rust-lang/mdBook/pull/2942)
 
 ### Theme changes
 
@@ -86,6 +115,10 @@ The following is a summary of the changes that may require your attention when u
   - [`mdbook-core`](https://docs.rs/mdbook-core/latest/mdbook_core/) — An internal library that is used by the other crates for shared types. You should not depend on this crate directly since types from this crate are re-exported from the other crates as appropriate.
 - Changes to `Config`:
   - [`Config::get`](https://docs.rs/mdbook-core/latest/mdbook_core/config/struct.Config.html#method.get) is now generic over the return value, using `serde` to deserialize the value. It also returns a `Result` to handle deserialization errors. [#2773](https://github.com/rust-lang/mdBook/pull/2773)
+  - [`Config::set`](https://docs.rs/mdbook-core/latest/mdbook_core/config/struct.Config.html#method.set) now validates that the config keys and values are valid.
+    [#2942](https://github.com/rust-lang/mdBook/pull/2942)
+  - [`Config::update_from_env`](https://docs.rs/mdbook-core/latest/mdbook_core/config/struct.Config.html#method.update_from_env) now returns a `Result` to indicate any errors.
+    [#2942](https://github.com/rust-lang/mdBook/pull/2942)
   - Removed `Config::get_deserialized`. Use `Config::get` instead.
   - Removed `Config::get_deserialized_opt`. Use `Config::get` instead.
   - Removed `Config::get_mut`. Use `Config::set` instead.

Cargo.lock

@@ -956,7 +956,7 @@ checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
 
 [[package]]
 name = "mdbook"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "axum",
@@ -996,7 +996,7 @@ version = "0.0.0"
 
 [[package]]
 name = "mdbook-core"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "regex",
@@ -1009,7 +1009,7 @@ dependencies = [
 
 [[package]]
 name = "mdbook-driver"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "indexmap",
@@ -1031,7 +1031,7 @@ dependencies = [
 
 [[package]]
 name = "mdbook-html"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "ego-tree",
@@ -1056,7 +1056,7 @@ dependencies = [
 
 [[package]]
 name = "mdbook-markdown"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 dependencies = [
  "pulldown-cmark",
  "regex",
@@ -1065,7 +1065,7 @@ dependencies = [
 
 [[package]]
 name = "mdbook-preprocessor"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "mdbook-core",
@@ -1085,7 +1085,7 @@ dependencies = [
 
 [[package]]
 name = "mdbook-renderer"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "mdbook-core",
@@ -1095,7 +1095,7 @@ dependencies = [
 
 [[package]]
 name = "mdbook-summary"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "mdbook-core",

Cargo.toml

@@ -39,13 +39,13 @@ hex = "0.4.3"
 html5ever = "0.35.0"
 indexmap = "2.12.0"
 ignore = "0.4.25"
-mdbook-core = { path = "crates/mdbook-core", version = "0.5.0-beta.2" }
-mdbook-driver = { path = "crates/mdbook-driver", version = "0.5.0-beta.2" }
-mdbook-html = { path = "crates/mdbook-html", version = "0.5.0-beta.2" }
-mdbook-markdown = { path = "crates/mdbook-markdown", version = "0.5.0-beta.2" }
-mdbook-preprocessor = { path = "crates/mdbook-preprocessor", version = "0.5.0-beta.2" }
-mdbook-renderer = { path = "crates/mdbook-renderer", version = "0.5.0-beta.2" }
-mdbook-summary = { path = "crates/mdbook-summary", version = "0.5.0-beta.2" }
+mdbook-core = { path = "crates/mdbook-core", version = "0.5.0" }
+mdbook-driver = { path = "crates/mdbook-driver", version = "0.5.0" }
+mdbook-html = { path = "crates/mdbook-html", version = "0.5.0" }
+mdbook-markdown = { path = "crates/mdbook-markdown", version = "0.5.0" }
+mdbook-preprocessor = { path = "crates/mdbook-preprocessor", version = "0.5.0" }
+mdbook-renderer = { path = "crates/mdbook-renderer", version = "0.5.0" }
+mdbook-summary = { path = "crates/mdbook-summary", version = "0.5.0" }
 memchr = "2.7.6"
 notify = "8.2.0"
 notify-debouncer-mini = "0.7.0"
@@ -71,7 +71,7 @@ walkdir = "2.5.0"
 
 [package]
 name = "mdbook"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 authors = [
     "Mathieu David <mathieudavid@mathieudavid.org>",
     "Michael-F-Bryan <michaelfbryan@gmail.com>",

crates/mdbook-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mdbook-core"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 description = "The base support library for mdbook, intended for internal use only"
 edition.workspace = true
 license.workspace = true

crates/mdbook-core/src/config.rs

@@ -123,11 +123,10 @@ impl Config {
     ///
     /// 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`
+    /// - `MDBOOK_book` -> `book`
+    /// - `MDBOOK_BOOK` -> `book`
+    /// - `MDBOOK_BOOK__TITLE` -> `book.title`
+    /// - `MDBOOK_BOOK__TEXT_DIRECTION` -> `book.text-direction`
     ///
     /// So by setting the `MDBOOK_BOOK__TITLE` environment variable you can
     /// override the book's title without needing to touch your `book.toml`.
@@ -147,7 +146,7 @@ impl Config {
     /// 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.
-    pub fn update_from_env(&mut self) {
+    pub fn update_from_env(&mut self) -> Result<()> {
         debug!("Updating the config from environment variables");
 
         let overrides =
@@ -162,19 +161,9 @@ impl Config {
             let parsed_value = serde_json::from_str(&value)
                 .unwrap_or_else(|_| serde_json::Value::String(value.to_string()));
 
-            if key == "book" || key == "build" {
-                if let serde_json::Value::Object(ref map) = parsed_value {
-                    // To `set` each `key`, we wrap them as `prefix.key`
-                    for (k, v) in map {
-                        let full_key = format!("{key}.{k}");
-                        self.set(&full_key, v).expect("unreachable");
-                    }
-                    return;
-                }
-            }
-
-            self.set(key, parsed_value).expect("unreachable");
+            self.set(key, parsed_value)?;
         }
+        Ok(())
     }
 
     /// Get a value from the configuration.
@@ -266,24 +255,39 @@ impl Config {
     /// `output.html.playground` will set the "playground" in the html output
     /// table).
     ///
-    /// The only way this can fail is if we can't serialize `value` into a
-    /// `toml::Value`.
+    /// # Errors
+    ///
+    /// This will fail if:
+    ///
+    /// - The value cannot be represented as TOML.
+    /// - The value is not a correct type.
+    /// - The key is an unknown configuration option.
     pub fn set<S: Serialize, I: AsRef<str>>(&mut self, index: I, value: S) -> Result<()> {
         let index = index.as_ref();
 
         let value = Value::try_from(value)
             .with_context(|| "Unable to represent the item as a JSON Value")?;
 
-        if let Some(key) = index.strip_prefix("book.") {
-            self.book.update_value(key, value);
+        if index == "book" {
+            self.book = value.try_into()?;
+        } else if index == "build" {
+            self.build = value.try_into()?;
+        } else if index == "rust" {
+            self.rust = value.try_into()?;
+        } else if index == "output" {
+            self.output = value;
+        } else if index == "preprocessor" {
+            self.preprocessor = value;
+        } else if let Some(key) = index.strip_prefix("book.") {
+            self.book.update_value(key, value)?;
         } else if let Some(key) = index.strip_prefix("build.") {
-            self.build.update_value(key, value);
+            self.build.update_value(key, value)?;
         } else if let Some(key) = index.strip_prefix("rust.") {
-            self.rust.update_value(key, value);
+            self.rust.update_value(key, value)?;
         } else if let Some(key) = index.strip_prefix("output.") {
-            self.output.update_value(key, value);
+            self.output.update_value(key, value)?;
         } else if let Some(key) = index.strip_prefix("preprocessor.") {
-            self.preprocessor.update_value(key, value);
+            self.preprocessor.update_value(key, value)?;
         } else {
             bail!("invalid key `{index}`");
         }
@@ -703,18 +707,13 @@ pub struct SearchChapterSettings {
 /// This is definitely not the most performant way to do things, which means you
 /// should probably keep it away from tight loops...
 trait Updateable<'de>: Serialize + Deserialize<'de> {
-    fn update_value<S: Serialize>(&mut self, key: &str, value: S) {
+    fn update_value<S: Serialize>(&mut self, key: &str, value: S) -> Result<()> {
         let mut raw = Value::try_from(&self).expect("unreachable");
-
-        if let Ok(value) = Value::try_from(value) {
-            raw.insert(key, value);
-        } else {
-            return;
-        }
-
-        if let Ok(updated) = raw.try_into() {
-            *self = updated;
-        }
+        let value = Value::try_from(value)?;
+        raw.insert(key, value);
+        let updated = raw.try_into()?;
+        *self = updated;
+        Ok(())
     }
 }
 

crates/mdbook-driver/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mdbook-driver"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 description = "High-level library for running mdBook"
 edition.workspace = true
 license.workspace = true

crates/mdbook-driver/src/mdbook.rs

@@ -56,7 +56,7 @@ impl MDBook {
             Config::default()
         };
 
-        config.update_from_env();
+        config.update_from_env()?;
 
         if tracing::enabled!(tracing::Level::TRACE) {
             for line in format!("Config: {config:#?}").lines() {

crates/mdbook-html/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mdbook-html"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 description = "mdBook HTML renderer"
 edition.workspace = true
 license.workspace = true

crates/mdbook-markdown/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mdbook-markdown"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 description = "Markdown processing used in mdBook"
 edition.workspace = true
 license.workspace = true

crates/mdbook-preprocessor/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mdbook-preprocessor"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 description = "Library to assist implementing an mdBook preprocessor"
 edition.workspace = true
 license.workspace = true

crates/mdbook-renderer/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mdbook-renderer"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 description = "Library to assist implementing an mdBook renderer"
 edition.workspace = true
 license.workspace = true

crates/mdbook-summary/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mdbook-summary"
-version = "0.5.0-beta.2"
+version = "0.5.0"
 description = "Summary parser for mdBook"
 edition.workspace = true
 license.workspace = true

guide/src/format/configuration/environment-variables.md

@@ -12,11 +12,10 @@ 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`
+- `MDBOOK_book` -> `book`
+- `MDBOOK_BOOK` -> `book`
+- `MDBOOK_BOOK__TITLE` -> `book.title`
+- `MDBOOK_BOOK__TEXT_DIRECTION` -> `book.text-direction`
 
 So by setting the `MDBOOK_BOOK__TITLE` environment variable you can override the
 book's title without needing to touch your `book.toml`.

tests/testsuite/config.rs

@@ -207,3 +207,137 @@ unknown field `title`, expected `edition`
 "#]]);
         });
 }
+
+// An invalid top-level key in the environment.
+#[test]
+fn env_invalid_config_key() {
+    BookTest::from_dir("config/empty").run("build", |cmd| {
+        cmd.env("MDBOOK_FOO", "testing")
+            .expect_failure()
+            .expect_stdout(str![[""]])
+            .expect_stderr(str![[r#"
+ERROR invalid key `foo`
+
+"#]]);
+    });
+}
+
+// An invalid value in the environment.
+#[test]
+fn env_invalid_value() {
+    BookTest::from_dir("config/empty")
+        .run("build", |cmd| {
+            cmd.env("MDBOOK_BOOK", r#"{"titlez": "typo"}"#)
+                .expect_failure()
+                .expect_stdout(str![[""]])
+                .expect_stderr(str![[r#"
+ERROR unknown field `titlez`, expected one of `title`, `authors`, `description`, `src`, `language`, `text-direction`
+
+
+"#]]);
+        })
+        .run("build", |cmd| {
+            cmd.env("MDBOOK_BOOK__TITLE", r#"{"looks like obj": "abc"}"#)
+                .expect_failure()
+                .expect_stdout(str![[""]])
+                .expect_stderr(str![[r#"
+ERROR invalid type: map, expected a string
+in `title`
+
+
+"#]]);
+        })
+        // This is not valid JSON, so falls back to be interpreted as a string.
+        .run("build", |cmd| {
+            cmd.env("MDBOOK_BOOK__TITLE", r#"{braces}"#)
+                .expect_stdout(str![[""]])
+                .expect_stderr(str![[r#"
+ INFO Book building has started
+ INFO Running the html backend
+ INFO HTML book written to `[ROOT]/book`
+
+"#]]);
+        })
+        .check_file_contains("book/index.html", "<title>Chapter 1 - {braces}</title>");
+}
+
+// Replacing the entire book table from the environment.
+#[test]
+fn env_entire_book_table() {
+    BookTest::init(|_| {})
+        .change_file(
+            "book.toml",
+            "[book]\n\
+             title = \"config title\"\n\
+            ",
+        )
+        .run("build", |cmd| {
+            cmd.env("MDBOOK_BOOK", r#"{"description": "custom description"}"#);
+        })
+        // The book.toml title is removed.
+        .check_file_contains("book/index.html", "<title>Chapter 1</title>")
+        .check_file_contains(
+            "book/index.html",
+            r#"<meta name="description" content="custom description">"#,
+        );
+}
+
+// Replacing the entire output or preprocessor table from the environment.
+#[test]
+fn env_entire_output_preprocessor_table() {
+    BookTest::from_dir("config/empty")
+        .rust_program(
+            "mdbook-my-preprocessor",
+            r#"
+            fn main() {
+                let mut args = std::env::args().skip(1);
+                if args.next().as_deref() == Some("supports") {
+                    return;
+                }
+                use std::io::Read;
+                let mut s = String::new();
+                std::io::stdin().read_to_string(&mut s).unwrap();
+                assert!(s.contains("custom preprocessor config"));
+                println!("{{\"items\": []}}");
+            }
+            "#,
+        )
+        .rust_program(
+            "mdbook-my-output",
+            r#"
+            fn main() {
+                use std::io::Read;
+                let mut s = String::new();
+                std::io::stdin().read_to_string(&mut s).unwrap();
+                assert!(s.contains("custom output config"));
+                eprintln!("preprocessor saw custom config");
+            }
+            "#,
+        )
+        .run("build", |cmd| {
+            let mut paths: Vec<_> =
+                std::env::split_paths(&std::env::var_os("PATH").unwrap_or_default()).collect();
+            paths.push(cmd.dir.clone());
+            let path = std::env::join_paths(paths).unwrap().into_string().unwrap();
+
+            cmd.env(
+                "MDBOOK_OUTPUT",
+                r#"{"my-output": {"foo": "custom output config"}}"#,
+            )
+            .env(
+                "MDBOOK_PREPROCESSOR",
+                r#"{"my-preprocessor": {"foo": "custom preprocessor config"}}"#,
+            )
+            .env("PATH", path)
+            .expect_stdout(str![[""]])
+            .expect_stderr(str![[r#"
+ INFO Book building has started
+ INFO Running the my-output backend
+ INFO Invoking the "my-output" renderer
+preprocessor saw custom config
+
+"#]]);
+        })
+        // No HTML output
+        .check_file_list("book", str![[""]]);
+}