readme: add more example projects

chore: prep v1.17.1 release

.github/workflows/check.yml

@@ -11,7 +11,7 @@ jobs:
       - name: Checkout sources
         uses: actions/checkout@v4
       - name: Cache build files
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             ~/.cargo/registry
@@ -19,10 +19,9 @@ jobs:
             target
           key: fast-test-${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.toml') }}
       - name: Install toolchain
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
           toolchain: stable
-          override: true
       - name: Install more toolchain
         run: rustup component add rustfmt clippy
       - name: Run tests
@@ -37,20 +36,20 @@ jobs:
       - name: Checkout sources
         uses: actions/checkout@v4
       - name: Cache build files
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             ~/.cargo/registry
             ~/.cargo/git
             target
             ~/.cargo/bin
-            cargo_target
+            /tmp/cargo-install-target-dir
           key: detailed-test-${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.toml') }}
       - name: Install toolchain
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
           toolchain: stable
-          override: true
+          components: rustfmt, clippy
       - name: Install node toolchain
         uses: actions/setup-node@v3
         with:
@@ -59,7 +58,7 @@ jobs:
           cache-dependency-path: compile_assets/yarn.lock
       - name: Install additional test dependencies
         env:
-          CARGO_TARGET_DIR: cargo_target
+          CARGO_TARGET_DIR: "/tmp/cargo-install-target-dir"
         run: ./scripts/install
       - name: Run check script
         run: ./scripts/check
@@ -105,7 +104,7 @@ jobs:
       - name: Checkout sources
         uses: actions/checkout@v4
       - name: Cache build files
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             ~/.cargo/registry
@@ -113,9 +112,8 @@ jobs:
             target
           key: test-${{ matrix.os }}-${{ matrix.rust }}-cargo-${{ hashFiles('**/Cargo.toml') }}
       - name: Install toolchain
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
           toolchain: ${{ matrix.rust }}
-          override: true
       - name: Run tests
         run: cargo test

.github/workflows/deploy.yml

@@ -43,19 +43,19 @@ jobs:
 
       # Cache files between builds
       - name: Setup | Cache Cargo
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
+          # Note that we don't cache the `target` directory here
+          # so we do a completely clean rebuild for artefacts
           path: |
             ~/.cargo/registry
             ~/.cargo/git
           key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
 
       - name: Setup | Rust
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
           toolchain: stable
-          override: true
-          profile: minimal
           target: ${{ matrix.target }}
 
       - name: Setup | cross
@@ -74,7 +74,7 @@ jobs:
 
       - name: Post Setup | Extract tag name
         shell: bash
-        run: echo "##[set-output name=tag;]$(echo ${GITHUB_REF#refs/tags/})"
+        run: echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
         id: extract_tag
 
       - name: Post Setup | Prepare artifacts [Windows]
@@ -113,7 +113,7 @@ jobs:
 
       - name: Setup | Extract version
         shell: bash
-        run: echo "##[set-output name=version;]$(echo ${GITHUB_REF#refs/tags/v})"
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
         id: extract_version
 
       - name: Setup | Release notes
@@ -134,21 +134,19 @@ jobs:
     runs-on: ubuntu-20.04
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         with:
           path: |
             ~/.cargo/registry
             ~/.cargo/git
             target
             ~/.cargo/bin
-            cargo_target
           # We reuse the cache from our detailed test environment, if available
           key: detailed-test-${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.toml') }}
       - name: Install toolchain
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
           toolchain: stable
-          override: true
       - name: Publish crate
         env:
           CARGO_LOGIN_TOKEN: ${{ secrets.CARGO_LOGIN_TOKEN }}

.github/workflows/docs.yml

@@ -14,24 +14,27 @@ jobs:
     runs-on: ubuntu-20.04
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         with:
           path: |
             ~/.cargo/registry
             ~/.cargo/git
             target
             ~/.cargo/bin
-            cargo_target
+            /tmp/cargo-install-target-dir
           # We reuse the cache from our detailed test environment, if available
           key: detailed-test-${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.toml') }}
       - name: Install toolchain
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
           toolchain: stable
-          override: true
       - name: Install mdbook
+        env:
+          CARGO_TARGET_DIR: "/tmp/cargo-install-target-dir"
         run: ./scripts/install-mdbook
       - name: Install mdbook extras
+        env:
+          CARGO_TARGET_DIR: "/tmp/cargo-install-target-dir"
         run: ./book/scripts/install-mdbook-extras
       - name: Build book
         run: ./scripts/build-book

CHANGELOG.md

@@ -1,10 +1,35 @@
 # Changelog
 
-## Unreleased
+## v1.17.1
+
+### Fixed
+
+- Removed a stray debug statement ([#186](https://github.com/tommilligan/mdbook-admonish/pull/186))
+
+## v1.17.0
+
+### Changed
+
+- Blocks should have key-value options separated by commas. Existing syntax remains is supported for back-compatibility. See [the documentation on Additional Options](https://tommilligan.github.io/mdbook-admonish/#additional-options) for more details ([#181](https://github.com/tommilligan/mdbook-admonish/pull/181))
+
+### Fixed
+
+- Titles contining `=` will now render correctly. Thanks to [@s00500](https://github.com/s00500) for the bug report! ([#181](https://github.com/tommilligan/mdbook-admonish/pull/181))
+
+## v1.16.0
 
 ### Changed
 
 - MSRV (minimum supported rust version) is now 1.74.0 ([#175](https://github.com/tommilligan/mdbook-admonish/pull/175))
+- `custom` directives should now be configured under the `directive.custom` option. Existing `custom` configurations are supported for back compatibility ([#179](https://github.com/tommilligan/mdbook-admonish/pull/174))
+
+### Added
+
+- Make blocks `collapsible` on a per-directive basis. Thanks to [@yannickseurin](https://github.com/yannickseurin) for contributing this feature! ([#174](https://github.com/tommilligan/mdbook-admonish/pull/174))
+
+### Fixed
+
+- The `css_id_prefix` option now uses snake case for consistency (kebab case remains supported for back compatibility). Thanks to [@yannickseurin](https://github.com/yannickseurin) for fixing this! ([#173](https://github.com/tommilligan/mdbook-admonish/pull/173))
 
 ## 1.15.0
 

Cargo.lock

@@ -967,7 +967,7 @@ dependencies = [
 
 [[package]]
 name = "mdbook-admonish"
-version = "1.15.0"
+version = "1.17.1"
 dependencies = [
  "anyhow",
  "clap",

Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "mdbook-admonish"
-version = "1.15.0"
+version = "1.17.1"
 edition = "2021"
-rust-version = "1.66.0"
+rust-version = "1.74.0"
 
 authors = ["Tom Milligan <code@tommilligan.net>"]
 description = "A preprocessor for mdbook to add Material Design admonishments."

README.md

@@ -21,9 +21,11 @@ into this:
 
 Read the documentation [here](https://tommilligan.github.io/mdbook-admonish/), to see the actual examples in action. You can see the source in the [`./book`](./book) subdirectory.
 
-Other projects using mdbook-admonish:
+Projects using mdbook-admonish include:
 
-- [The Rhai Book](https://rhai.rs/book/)
+- [The Rhai Book](https://rhai.rs/book/) ([source](https://github.com/rhaiscript/book))
+- [The Trunk Guide](https://trunkrs.dev/guide/) ([source](https://github.com/trunk-rs/trunk))
+- [PRQL language book](https://prql-lang.org/book/) ([source](https://github.com/PRQL/prql))
 
 ## Usage
 

book/book.toml

@@ -10,12 +10,10 @@ git-repository-url = "https://github.com/tommilligan/mdbook-admonish"
 
 [preprocessor.admonish]
 command = "mdbook-admonish"
-assets_version = "3.0.1" # do not edit: managed by `mdbook-admonish install`
+assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install`
 
-[[preprocessor.admonish.custom]]
-directive = "expensive"
-icon = "./money-bag.svg"
-color = "#24ab38"
+[preprocessor.admonish.directive.custom]
+expensive = { icon = "./money-bag.svg", color = "#24ab38" }
 
 [preprocessor.toc]
 command = "mdbook-toc"

book/src/SUMMARY.md

@@ -2,3 +2,4 @@
 
 - [Overview](./overview.md)
 - [Reference](./reference.md)
+- [Examples](./examples.md)

book/src/examples.md

@@ -0,0 +1,15 @@
+# Examples
+
+## Combining multiple custom properties
+
+Note that the comma `,` is used to seperate custom options.
+
+````
+```admonish quote collapsible=true, title='A title that really <span style="color: #e70073">pops</span>'
+To really <b><span style="color: #e70073">grab</span></b> your reader's attention.
+```
+````
+
+```admonish quote collapsible=true, title='A title that really <span style="color: #e70073">pops</span>'
+To really <b><span style="color: #e70073">grab</span></b> your reader's attention.
+```

book/src/overview.md

@@ -78,14 +78,19 @@ You can also configure the build to fail loudly, by setting `on_failure = "bail"
 
 ### Additional Options
 
-You can pass additional options to each block. The options are structured as TOML key-value pairs.
+You can pass additional options to each block. Options are given like a [TOML Inline Table](https://toml.io/en/v1.0.0#inline-table), as key-value pairs separated by commas.
+
+`mdbook-admonish` parses options by wrapping your options in an inline table before parsing them, so please consult [The TOML Reference](https://toml.io) if you run into any syntax errors. Be aware that:
+
+- Key-value pairs must be separated with a comma `,`
+- TOML escapes must be escaped again - for instance, write `\"` as `\\"`.
+- For complex strings such as HTML, you may want to use a [literal string](https://toml.io/en/v1.0.0#string) to avoid complex escape sequences
 
 Note that some options can be passed globally, through the `default` section in `book.toml`. See the [configuration reference](./reference.md#booktoml-configuration) for more details.
 
 #### Custom title
 
-A custom title can be provided, contained in a double quoted TOML string.
-Note that TOML escapes must be escaped again - for instance, write `\"` as `\\"`.
+A custom title can be provided:
 
 ````
 ```admonish warning title="Data loss"
@@ -114,13 +119,13 @@ This will take a while, go and grab a drink of water.
 Markdown and HTML can be used in the inner content, as you'd expect:
 
 ````
-```admonish tip title="_Referencing_ and <i>dereferencing</i>"
+```admonish tip title='_Referencing_ and <i>dereferencing</i>'
 The opposite of *referencing* by using `&` is *dereferencing*, which is
 accomplished with the <span style="color: hotpink">dereference operator</span>, `*`.
 ```
 ````
 
-```admonish tip title="_Referencing_ and <i>dereferencing</i>"
+```admonish tip title='_Referencing_ and <i>dereferencing</i>'
 The opposite of *referencing* by using `&` is *dereferencing*, which is
 accomplished with the <span style="color: hotpink">dereference operator</span>, `*`.
 ```
@@ -148,7 +153,7 @@ print "Hello, world!"
 If you want to provide custom styling to a specific admonition, you can attach one or more custom classnames:
 
 ````
-```admonish note class="custom-0 custom-1"
+```admonish note title="Stylish", class="custom-0 custom-1"
 Styled with my custom CSS class.
 ```
 ````
@@ -173,7 +178,7 @@ with an appended number if multiple blocks would have the same id.
 Setting the `id` field will _ignore_ all other ids and the duplicate counter.
 
 ````
-```admonish info title="My Info" id="my-special-info"
+```admonish info title="My Info", id="my-special-info"
 Link to this block with `#my-special-info` instead of the default `#admonition-my-info`.
 ```
 ````
@@ -183,14 +188,14 @@ Link to this block with `#my-special-info` instead of the default `#admonition-m
 For a block to be initially collapsible, and then be openable, set `collapsible=true`:
 
 ````
-```admonish collapsible=true
+```admonish title="Sneaky", collapsible=true
 Content will be hidden initially.
 ```
 ````
 
 Will yield something like the following HTML, which you can then apply styles to:
 
-```admonish collapsible=true
+```admonish title="Sneaky", collapsible=true
 Content will be hidden initially.
 ```
 

book/src/reference.md

@@ -75,28 +75,50 @@ Subfields:
     - For the `html` renderer, the default value is `html`.
     - For all other renderers, the default value is `preserve`.
 
-### `custom`
+### `directive`
 
 Optional.
 
-Additional type of block to support.
-You must run `mdbook-admonish generate-custom` after updating these values, to generate the correct styles.
+Settings relating to each type of block.
 
-Add blocks using TOML's [Array of Tables](https://toml.io/en/v1.0.0#array-of-tables) notation:
+#### `builtin`
+
+Optional.
+
+Override the settings of a builtin directive.
+
+The subkey of `builtin` is the directive to override. This must be the first directive listed in the [Directives](#directives) section below, e.g. `warning` (not `caution` or other aliases).
 
 ```toml
-[[preprocessor.admonish.custom]]
-directive = "expensive"
+[preprocessor.admonish.directive.builtin.warning]
+collapsible = true
+```
+
+Subfields:
+
+- `collapsible` (optional): The default boolean value of the collapsible property for this type of block.
+
+#### `custom`
+
+Optional.
+
+Additional types of block to support. The subkey of `custom` is the new directive to support.
+
+You must run `mdbook-admonish generate-custom` after updating these values, to generate the correct styles.
+
+```toml
+[preprocessor.admonish.directive.custom.expensive]
 icon = "./money-bag.svg"
 color = "#24ab38"
+collapsible = true
 aliases = ["money", "cash", "budget"]
 ```
 
 Subfields:
 
-- `directive`: The keyword to use this type of block.
 - `icon`: A filepath relative to the book root to load an SVG icon from.
 - `color`: An RGB hex encoded color to use for the icon.
+- `collapsible` (optional): The default boolean value of the collapsible property for this type of block.
 - `aliases` (optional): One or more alternative directives to use this block.
 - `title` (optional): The default title for this type of block. If not specified, defaults to the directive in title case. To give each alias a custom title, add multiple custom blocks.
 

integration/expected/chapter_1_main.html

@@ -39,10 +39,12 @@
 </div>
 <div>
 <p>Failed with:</p>
-<pre><code class="language-log">TOML parsing error: TOML parse error at line 1, column 8
+<pre><code class="language-log">'title=&quot;' is not a valid directive or TOML key-value pair.
+
+TOML parsing error: TOML parse error at line 1, column 21
   |
-1 | title=&quot;
-  |        ^
+1 | config = { title=&quot; }
+  |                     ^
 invalid basic string
 
 </code></pre>

src/book_config.rs

@@ -4,7 +4,7 @@ use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::path::PathBuf;
 
-use crate::types::AdmonitionDefaults;
+use crate::types::{AdmonitionDefaults, BuiltinDirective, BuiltinDirectiveConfig};
 
 /// Loads the plugin configuration from mdbook internals.
 ///
@@ -20,9 +20,42 @@ pub(crate) fn admonish_config_from_context(ctx: &PreprocessorContext) -> Result<
 }
 
 pub(crate) fn admonish_config_from_str(data: &str) -> Result<Config> {
-    toml::from_str(data).context("Invalid mdbook-admonish configuration in book.toml")
+    let readonly: ConfigReadonly =
+        toml::from_str(data).context("Invalid mdbook-admonish configuration in book.toml")?;
+    let config = readonly.into();
+    log::debug!("Loaded admonish config: {:?}", config);
+    Ok(config)
 }
 
+/// All valid input states including back-compatibility fields.
+///
+/// This struct deliberately does not implement Serialize as it never meant to
+/// be written, only converted to Config.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Default)]
+struct ConfigReadonly {
+    #[serde(default)]
+    pub on_failure: OnFailure,
+
+    #[serde(default)]
+    pub default: AdmonitionDefaults,
+
+    #[serde(default)]
+    pub renderer: HashMap<String, RendererConfig>,
+
+    #[serde(default)]
+    pub assets_version: Option<String>,
+
+    #[serde(default)]
+    pub custom: Vec<CustomDirectiveReadonly>,
+
+    #[serde(default)]
+    pub builtin: HashMap<BuiltinDirective, BuiltinDirectiveConfig>,
+
+    #[serde(default)]
+    pub directive: DirectiveConfig,
+}
+
+/// The canonical config format, without back-compatibility
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, Default)]
 pub(crate) struct Config {
     #[serde(default)]
@@ -38,14 +71,50 @@ pub(crate) struct Config {
     pub assets_version: Option<String>,
 
     #[serde(default)]
-    pub custom: Vec<CustomDirective>,
+    pub directive: DirectiveConfig,
+}
+
+impl From<ConfigReadonly> for Config {
+    fn from(other: ConfigReadonly) -> Self {
+        let ConfigReadonly {
+            on_failure,
+            default,
+            renderer,
+            assets_version,
+            custom,
+            builtin,
+            mut directive,
+        } = other;
+
+        // Merge deprecated config fields into main config object
+        directive.custom.extend(
+            custom
+                .into_iter()
+                .map(|CustomDirectiveReadonly { directive, config }| (directive, config)),
+        );
+        directive.builtin.extend(builtin);
+
+        Self {
+            on_failure,
+            default,
+            renderer,
+            assets_version,
+            directive,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, Default)]
+pub(crate) struct DirectiveConfig {
+    #[serde(default)]
+    pub custom: HashMap<String, CustomDirective>,
+
+    #[serde(default)]
+    pub builtin: HashMap<BuiltinDirective, BuiltinDirectiveConfig>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
 pub(crate) struct CustomDirective {
-    /// The primary directive. Used for CSS classnames
-    pub directive: String,
-
     /// Path to an SVG file, relative to the book root.
     pub icon: PathBuf,
 
@@ -59,6 +128,20 @@ pub(crate) struct CustomDirective {
     /// Title to use, human readable.
     #[serde(default)]
     pub title: Option<String>,
+
+    /// Default collapsible value.
+    #[serde(default)]
+    pub collapsible: Option<bool>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+pub(crate) struct CustomDirectiveReadonly {
+    /// The primary directive. Used for CSS classnames
+    pub directive: String,
+
+    /// Path to an SVG file, relative to the book root.
+    #[serde(flatten)]
+    config: CustomDirective,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
@@ -92,6 +175,8 @@ mod test {
     use super::*;
     use pretty_assertions::assert_eq;
 
+    use crate::types::BuiltinDirective;
+
     #[test]
     fn empty_config_okay() -> Result<()> {
         let actual = admonish_config_from_str("")?;
@@ -120,6 +205,57 @@ mod test {
         Ok(())
     }
 
+    #[test]
+    fn merge_old_and_new_custom_directives() -> Result<()> {
+        let serialized = r##"
+[directive.custom.purple]
+icon = "/tmp/test-directive.svg"
+color = "#9B4F96"
+aliases = ["test-directive-alias-0"]
+title = "Purple"
+collapsible = true
+
+[[custom]]
+directive = "blue"
+icon = "/tmp/test-directive.svg"
+color = "#0038A8"
+aliases = []
+title = "Blue"
+        "##;
+        let expected = Config {
+            directive: DirectiveConfig {
+                custom: HashMap::from([
+                    (
+                        "purple".to_owned(),
+                        CustomDirective {
+                            icon: PathBuf::from("/tmp/test-directive.svg"),
+                            color: hex_color::HexColor::from((155, 79, 150)),
+                            aliases: vec!["test-directive-alias-0".to_owned()],
+                            title: Some("Purple".to_owned()),
+                            collapsible: Some(true),
+                        },
+                    ),
+                    (
+                        "blue".to_owned(),
+                        CustomDirective {
+                            icon: PathBuf::from("/tmp/test-directive.svg"),
+                            color: hex_color::HexColor::from((0, 56, 168)),
+                            aliases: vec![],
+                            title: Some("Blue".to_owned()),
+                            collapsible: None,
+                        },
+                    ),
+                ]),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+
+        let actual = admonish_config_from_str(serialized)?;
+        assert_eq!(actual, expected);
+        Ok(())
+    }
+
     #[test]
     fn full_config_roundtrip() -> Result<()> {
         let input = Config {
@@ -129,13 +265,24 @@ mod test {
                 title: Some("".to_owned()),
             },
             assets_version: Some("1.1.1".to_owned()),
-            custom: vec![CustomDirective {
-                directive: "test-directive".to_owned(),
-                icon: PathBuf::from("/tmp/test-directive.svg"),
-                color: hex_color::HexColor::from((155, 79, 150)),
-                aliases: vec!["test-directive-alias-0".to_owned()],
-                title: Some("test-directive-title".to_owned()),
-            }],
+            directive: DirectiveConfig {
+                custom: HashMap::from([(
+                    "test-directive".to_owned(),
+                    CustomDirective {
+                        icon: PathBuf::from("/tmp/test-directive.svg"),
+                        color: hex_color::HexColor::from((155, 79, 150)),
+                        aliases: vec!["test-directive-alias-0".to_owned()],
+                        title: Some("test-directive-title".to_owned()),
+                        collapsible: Some(true),
+                    },
+                )]),
+                builtin: HashMap::from([(
+                    BuiltinDirective::Warning,
+                    BuiltinDirectiveConfig {
+                        collapsible: Some(true),
+                    },
+                )]),
+            },
             on_failure: OnFailure::Bail,
             renderer: HashMap::from([(
                 "test-mode".to_owned(),
@@ -156,12 +303,15 @@ css_id_prefix = "flam-"
 [renderer.test-mode]
 render_mode = "strip"
 
-[[custom]]
-directive = "test-directive"
+[directive.custom.test-directive]
 icon = "/tmp/test-directive.svg"
 color = "#9B4F96"
 aliases = ["test-directive-alias-0"]
 title = "test-directive-title"
+collapsible = true
+
+[directive.builtin.warning]
+collapsible = true
 "##;
 
         let serialized = toml::to_string(&input)?;

src/config/mod.rs

@@ -1,11 +1,13 @@
+mod toml_wrangling;
 mod v1;
 mod v2;
+mod v3;
 
 /// Configuration as described by the instance of an admonition in markdown.
 ///
 /// This structure represents the configuration the user must provide in each
 /// instance.
-#[derive(Debug, PartialEq)]
+#[derive(Debug, PartialEq, Default)]
 pub(crate) struct InstanceConfig {
     pub(crate) directive: String,
     pub(crate) title: Option<String>,
@@ -35,20 +37,29 @@ impl InstanceConfig {
     /// - `Some(InstanceConfig)` if this is an `admonish` block
     pub fn from_info_string(info_string: &str) -> Option<Result<Self, String>> {
         let config_string = admonition_config_string(info_string)?;
+        Some(Self::from_admonish_config_string(config_string))
+    }
 
-        // If we succeed at parsing v2, return that. Otherwise hold onto the error
-        let config_v2_error = match v2::from_config_string(config_string) {
-            Ok(config) => return Some(Ok(config)),
-            Err(config) => config,
+    /// Parse an info string that is known to be for `admonish`.
+    fn from_admonish_config_string(config_string: &str) -> Result<Self, String> {
+        // If we succeed at parsing v3, return that. Otherwise hold onto the error
+        let config_v3_error = match v3::from_config_string(config_string) {
+            Ok(config) => return Ok(config),
+            Err(error) => error,
         };
 
-        Some(if let Ok(config) = v1::from_config_string(config_string) {
-            // If we succeed at parsing v1, return that.
-            Ok(config)
-        } else {
-            // Otherwise return our v2 error.
-            Err(config_v2_error)
-        })
+        // If we succeed at parsing v2, return that
+        if let Ok(config) = v2::from_config_string(config_string) {
+            return Ok(config);
+        };
+
+        // If we succeed at parsing v1, return that.
+        if let Ok(config) = v1::from_config_string(config_string) {
+            return Ok(config);
+        }
+
+        // Otherwise return our v3 error.
+        Err(config_v3_error)
     }
 }
 
@@ -90,5 +101,20 @@ mod test {
                 collapsible: None,
             }
         );
+        // v3 syntax is supported
+        assert_eq!(
+            InstanceConfig::from_info_string(
+                r#"admonish title="Custom Title", type="question", id="my-id""#
+            )
+            .unwrap()
+            .unwrap(),
+            InstanceConfig {
+                directive: "question".to_owned(),
+                title: Some("Custom Title".to_owned()),
+                id: Some("my-id".to_owned()),
+                additional_classnames: Vec::new(),
+                collapsible: None,
+            }
+        );
     }
 }

src/config/toml_wrangling.rs

@@ -0,0 +1,44 @@
+use once_cell::sync::Lazy;
+use regex::Regex;
+use serde::Deserialize;
+use std::fmt::Display;
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub(crate) struct UserInput {
+    #[serde(default)]
+    pub r#type: Option<String>,
+    #[serde(default)]
+    pub title: Option<String>,
+    #[serde(default)]
+    pub id: Option<String>,
+    #[serde(default)]
+    pub class: Option<String>,
+    #[serde(default)]
+    pub collapsible: Option<bool>,
+}
+
+impl UserInput {
+    pub fn classnames(&self) -> Vec<String> {
+        self.class
+            .as_ref()
+            .map(|class| {
+                class
+                    .split(' ')
+                    .filter(|classname| !classname.is_empty())
+                    .map(|classname| classname.to_owned())
+                    .collect()
+            })
+            .unwrap_or_default()
+    }
+}
+
+pub(crate) static RX_DIRECTIVE: Lazy<Regex> =
+    Lazy::new(|| Regex::new(r#"^[A-Za-z0-9_-]+$"#).expect("directive regex"));
+
+pub(crate) fn format_toml_parsing_error(error: impl Display) -> String {
+    format!("TOML parsing error: {error}")
+}
+
+pub(crate) fn format_invalid_directive(directive: &str, original_error: impl Display) -> String {
+    format!("'{directive}' is not a valid directive or TOML key-value pair.\n\n{original_error}")
+}

src/config/v2.rs

@@ -1,30 +1,16 @@
+use super::toml_wrangling::{
+    format_invalid_directive, format_toml_parsing_error, UserInput, RX_DIRECTIVE,
+};
 use super::InstanceConfig;
 use once_cell::sync::Lazy;
 use regex::Regex;
-use serde::Deserialize;
-
-#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
-struct UserInput {
-    #[serde(default)]
-    r#type: Option<String>,
-    #[serde(default)]
-    title: Option<String>,
-    #[serde(default)]
-    id: Option<String>,
-    #[serde(default)]
-    class: Option<String>,
-    #[serde(default)]
-    collapsible: Option<bool>,
-}
 
 /// Transform our config string into valid toml
 fn bare_key_value_pairs_to_toml(pairs: &str) -> String {
     use regex::Captures;
 
-    static RX_BARE_KEY_ASSIGNMENT: Lazy<Regex> = Lazy::new(|| {
-        let bare_key = r#"[A-Za-z0-9_-]+"#;
-        Regex::new(&format!("(?:{bare_key}) *=")).expect("bare key assignment regex")
-    });
+    static RX_BARE_KEY_ASSIGNMENT: Lazy<Regex> =
+        Lazy::new(|| Regex::new(r#"(?:[A-Za-z0-9_-]+) *="#).expect("bare key assignment regex"));
 
     fn prefix_with_newline(captures: &Captures) -> String {
         format!(
@@ -41,10 +27,18 @@ fn bare_key_value_pairs_to_toml(pairs: &str) -> String {
         .into_owned()
 }
 
+fn user_input_from_config_toml(config_toml: &str) -> Result<UserInput, String> {
+    toml::from_str(config_toml).map_err(format_toml_parsing_error)
+}
+
 /// Parse and return the config assuming v2 format.
 ///
 /// Note that if an error occurs, a parsed struct that can be returned to
 /// show the error message will be returned.
+///
+/// The basic idea here is to accept space separated key-value pairs, break them
+/// onto separate lines, and then parse them as a TOML document.
+/// This breaks when values contain a literal '=' sign, for which v3 syntax should be used.
 pub(crate) fn from_config_string(config_string: &str) -> Result<InstanceConfig, String> {
     let config_toml = bare_key_value_pairs_to_toml(config_string);
     let config_toml = config_toml.trim();
@@ -52,7 +46,7 @@ pub(crate) fn from_config_string(config_string: &str) -> Result<InstanceConfig,
     let config: UserInput = match toml::from_str(config_toml) {
         Ok(config) => config,
         Err(error) => {
-            let original_error = Err(format!("TOML parsing error: {error}"));
+            let original_error = format_toml_parsing_error(error);
 
             // For ergonomic reasons, we allow users to specify the directive without
             // a key. So if parsing fails initially, take the first line,
@@ -62,17 +56,11 @@ pub(crate) fn from_config_string(config_string: &str) -> Result<InstanceConfig,
                 None => (config_toml, ""),
             };
 
-            static RX_DIRECTIVE: Lazy<Regex> =
-                Lazy::new(|| Regex::new(r#"^[A-Za-z0-9_-]+$"#).expect("directive regex"));
-
             if !RX_DIRECTIVE.is_match(directive) {
-                return original_error;
+                return Err(format_invalid_directive(directive, original_error));
             }
 
-            let mut config: UserInput = match toml::from_str(config_toml) {
-                Ok(config) => config,
-                Err(_) => return original_error,
-            };
+            let mut config = user_input_from_config_toml(config_toml)?;
             config.r#type = Some(directive.to_owned());
             config
         }
@@ -102,97 +90,120 @@ mod test {
     use pretty_assertions::assert_eq;
 
     #[test]
-    fn test_from_config_string_v2() {
-        assert_eq!(
-            from_config_string("").unwrap(),
+    fn test_from_config_string_v2() -> Result<(), ()> {
+        fn check(config_string: &str, expected: InstanceConfig) -> Result<(), ()> {
+            let actual = match from_config_string(config_string) {
+                Ok(config) => config,
+                Err(error) => panic!("Expected config to be valid, got error:\n\n{}", error),
+            };
+            assert_eq!(actual, expected);
+            Ok(())
+        }
+
+        check(
+            "",
             InstanceConfig {
                 directive: "".to_owned(),
                 title: None,
                 id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
-            }
-        );
-        assert_eq!(
-            from_config_string(" ").unwrap(),
+            },
+        )?;
+        check(
+            " ",
             InstanceConfig {
                 directive: "".to_owned(),
                 title: None,
                 id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
-            }
-        );
-        assert_eq!(
-            from_config_string(
-                r#"type="note" class="additional classname" title="Никита" collapsible=true"#
-            )
-            .unwrap(),
+            },
+        )?;
+        check(
+            r#"type="note" class="additional classname" title="Никита" collapsible=true"#,
             InstanceConfig {
                 directive: "note".to_owned(),
                 title: Some("Никита".to_owned()),
                 id: None,
                 additional_classnames: vec!["additional".to_owned(), "classname".to_owned()],
                 collapsible: Some(true),
-            }
-        );
+            },
+        )?;
         // Specifying unknown keys is okay, as long as they're valid
-        assert_eq!(
-            from_config_string(r#"unkonwn="but valid toml""#).unwrap(),
+        check(
+            r#"unkonwn="but valid toml""#,
             InstanceConfig {
                 directive: "".to_owned(),
                 title: None,
                 id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
-            }
-        );
+            },
+        )?;
         // Just directive is fine
-        assert_eq!(
-            from_config_string(r#"info"#).unwrap(),
+        check(
+            r#"info"#,
             InstanceConfig {
                 directive: "info".to_owned(),
                 title: None,
                 id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
-            }
-        );
+            },
+        )?;
         // Directive plus toml config
-        assert_eq!(
-            from_config_string(r#"info title="Information" collapsible=false"#).unwrap(),
+        check(
+            r#"info title="Information" collapsible=false"#,
             InstanceConfig {
                 directive: "info".to_owned(),
                 title: Some("Information".to_owned()),
                 id: None,
                 additional_classnames: Vec::new(),
                 collapsible: Some(false),
-            }
-        );
+            },
+        )?;
         // Test custom id
-        assert_eq!(
-            from_config_string(r#"info title="My Info" id="my-info-custom-id""#).unwrap(),
+        check(
+            r#"info title="My Info" id="my-info-custom-id""#,
             InstanceConfig {
                 directive: "info".to_owned(),
                 title: Some("My Info".to_owned()),
                 id: Some("my-info-custom-id".to_owned()),
                 additional_classnames: Vec::new(),
                 collapsible: None,
-            }
-        );
+            },
+        )?;
         // Directive after toml config is an error
         assert!(from_config_string(r#"title="Information" info"#).is_err());
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_from_config_string_invalid_directive() {
+        assert_eq!(
+            from_config_string(r#"oh!wow titlel=""#).unwrap_err(),
+            r#"'oh!wow' is not a valid directive or TOML key-value pair.
+
+TOML parsing error: TOML parse error at line 1, column 3
+  |
+1 | oh!wow 
+  |   ^
+expected `.`, `=`
+"#
+        );
     }
 
     #[test]
     fn test_from_config_string_invalid_toml_value() {
         assert_eq!(
             from_config_string(r#"note titlel=""#).unwrap_err(),
-            r#"TOML parsing error: TOML parse error at line 1, column 6
+            r#"TOML parsing error: TOML parse error at line 1, column 9
   |
-1 | note 
-  |      ^
-expected `.`, `=`
+1 | titlel="
+  |         ^
+invalid basic string
 "#
         );
     }

src/config/v3.rs

@@ -0,0 +1,202 @@
+use super::toml_wrangling::{
+    format_invalid_directive, format_toml_parsing_error, UserInput, RX_DIRECTIVE,
+};
+use super::InstanceConfig;
+use serde::Deserialize;
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+struct Wrapper<T> {
+    config: T,
+}
+
+/// Transform our config string into valid toml
+fn bare_inline_table_to_toml(pairs: &str) -> String {
+    format!("config = {{ {pairs} }}")
+}
+
+fn user_input_from_config_string(config_string: &str) -> Result<UserInput, String> {
+    match toml::from_str::<Wrapper<_>>(&bare_inline_table_to_toml(config_string)) {
+        Ok(wrapper) => Ok(wrapper.config),
+        Err(error) => Err(format_toml_parsing_error(error)),
+    }
+}
+
+/// Parse and return the config assuming v3 format.
+///
+/// Note that if an error occurs, a parsed struct that can be returned to
+/// show the error message will be returned.
+///
+/// The basic idea here is to accept the inside of an inline table, wrap it,
+/// parse it, and then use the toml values.
+pub(crate) fn from_config_string(config_string: &str) -> Result<InstanceConfig, String> {
+    let config_string = config_string.trim();
+
+    let config = match user_input_from_config_string(config_string) {
+        Ok(config) => config,
+        Err(error) => {
+            // For ergonomic reasons, we allow users to specify the directive without
+            // a key. So if parsing fails initially, take the first word,
+            // use that as the directive, and reparse.
+            let (directive, config_string) = match config_string.split_once(' ') {
+                Some((directive, config_string)) => (directive.trim(), config_string.trim()),
+                None => (config_string, ""),
+            };
+
+            if !RX_DIRECTIVE.is_match(directive) {
+                return Err(format_invalid_directive(directive, error));
+            }
+
+            let mut config = user_input_from_config_string(config_string)?;
+            config.r#type = Some(directive.to_owned());
+            config
+        }
+    };
+
+    let additional_classnames = config.classnames();
+    Ok(InstanceConfig {
+        directive: config.r#type.unwrap_or_default(),
+        title: config.title,
+        id: config.id,
+        additional_classnames,
+        collapsible: config.collapsible,
+    })
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn test_from_config_string_v3() -> Result<(), ()> {
+        fn check(config_string: &str, expected: InstanceConfig) -> Result<(), ()> {
+            let actual = match from_config_string(config_string) {
+                Ok(config) => config,
+                Err(error) => {
+                    panic!("Expected config '{config_string}' to be valid, got error:\n\n{error}")
+                }
+            };
+            assert_eq!(actual, expected);
+            Ok(())
+        }
+
+        check(
+            "",
+            InstanceConfig {
+                directive: "".to_owned(),
+                title: None,
+                id: None,
+                additional_classnames: Vec::new(),
+                collapsible: None,
+            },
+        )?;
+        check(
+            " ",
+            InstanceConfig {
+                directive: "".to_owned(),
+                title: None,
+                id: None,
+                additional_classnames: Vec::new(),
+                collapsible: None,
+            },
+        )?;
+        check(
+            r#"type="note", class="additional classname", title="Никита", collapsible=true"#,
+            InstanceConfig {
+                directive: "note".to_owned(),
+                title: Some("Никита".to_owned()),
+                id: None,
+                additional_classnames: vec!["additional".to_owned(), "classname".to_owned()],
+                collapsible: Some(true),
+            },
+        )?;
+        // Specifying unknown keys is okay, as long as they're valid
+        check(
+            r#"unkonwn="but valid toml""#,
+            InstanceConfig {
+                directive: "".to_owned(),
+                title: None,
+                id: None,
+                additional_classnames: Vec::new(),
+                collapsible: None,
+            },
+        )?;
+        // Just directive is fine
+        check(
+            r#"info"#,
+            InstanceConfig {
+                directive: "info".to_owned(),
+                title: None,
+                id: None,
+                additional_classnames: Vec::new(),
+                collapsible: None,
+            },
+        )?;
+        // Directive plus toml config
+        check(
+            r#"info title="Information", collapsible=false"#,
+            InstanceConfig {
+                directive: "info".to_owned(),
+                title: Some("Information".to_owned()),
+                id: None,
+                additional_classnames: Vec::new(),
+                collapsible: Some(false),
+            },
+        )?;
+        // Test custom id
+        check(
+            r#"info title="My Info", id="my-info-custom-id""#,
+            InstanceConfig {
+                directive: "info".to_owned(),
+                title: Some("My Info".to_owned()),
+                id: Some("my-info-custom-id".to_owned()),
+                additional_classnames: Vec::new(),
+                collapsible: None,
+            },
+        )?;
+        // Directive after toml config is an error
+        assert!(from_config_string(r#"title="Information" info"#).is_err());
+        // HTML with quotes inside content
+        // Note that we use toml literal (single quoted) strings here
+        check(
+            r#"info title='My <span class="emphasis">Title</span>'"#,
+            InstanceConfig {
+                directive: "info".to_owned(),
+                title: Some(r#"My <span class="emphasis">Title</span>"#.to_owned()),
+                id: None,
+                additional_classnames: Vec::new(),
+                collapsible: None,
+            },
+        )?;
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_from_config_string_invalid_directive() {
+        assert_eq!(
+            from_config_string(r#"oh!wow titlel=""#).unwrap_err(),
+            r#"'oh!wow' is not a valid directive or TOML key-value pair.
+
+TOML parsing error: TOML parse error at line 1, column 14
+  |
+1 | config = { oh!wow titlel=" }
+  |              ^
+expected `.`, `=`
+"#
+        );
+    }
+
+    #[test]
+    fn test_from_config_string_invalid_toml_value() {
+        assert_eq!(
+            from_config_string(r#"note titlel=""#).unwrap_err(),
+            r#"TOML parsing error: TOML parse error at line 1, column 22
+  |
+1 | config = { titlel=" }
+  |                      ^
+invalid basic string
+"#
+        );
+    }
+}

src/custom.rs

@@ -70,7 +70,7 @@ fn directive_css(name: &str, svg_data: &str, tint: HexColor) -> String {
 #[doc(hidden)]
 pub fn css_from_config(book_dir: &Path, config: &str) -> Result<String> {
     let config = crate::book_config::admonish_config_from_str(config)?;
-    let custom_directives = config.custom;
+    let custom_directives = config.directive.custom;
 
     if custom_directives.is_empty() {
         return Err(anyhow!("No custom directives provided"));
@@ -78,10 +78,10 @@ pub fn css_from_config(book_dir: &Path, config: &str) -> Result<String> {
 
     log::info!("Loaded {} custom directives", custom_directives.len());
     let mut css = String::new();
-    for directive in custom_directives.iter() {
+    for (directive_name, directive) in custom_directives.iter() {
         let svg = fs::read_to_string(book_dir.join(&directive.icon))
             .with_context(|| format!("can't read icon file '{}'", directive.icon.display()))?;
-        css.push_str(&directive_css(&directive.directive, &svg, directive.color));
+        css.push_str(&directive_css(directive_name, &svg, directive.color));
     }
     Ok(css)
 }

src/markdown.rs

@@ -4,14 +4,13 @@ use pulldown_cmark::{CodeBlockKind::*, Event, Options, Parser, Tag};
 use crate::{
     book_config::OnFailure,
     parse::parse_admonition,
-    types::{AdmonitionDefaults, CustomDirectiveMap, RenderTextMode},
+    types::{Overrides, RenderTextMode},
 };
 
 pub(crate) fn preprocess(
     content: &str,
     on_failure: OnFailure,
-    admonition_defaults: &AdmonitionDefaults,
-    custom_directives: &CustomDirectiveMap,
+    overrides: &Overrides,
     render_text_mode: RenderTextMode,
 ) -> MdbookResult<String> {
     let mut id_counter = Default::default();
@@ -33,8 +32,7 @@ pub(crate) fn preprocess(
 
             let admonition = match parse_admonition(
                 info_string.as_ref(),
-                admonition_defaults,
-                custom_directives,
+                overrides,
                 span_content,
                 on_failure,
                 indent,
@@ -92,9 +90,12 @@ fn indent_of(content: &str, position: usize, max: usize) -> usize {
 
 #[cfg(test)]
 mod test {
-    use super::*;
     use pretty_assertions::assert_eq;
 
+    use crate::types::AdmonitionDefaults;
+
+    use super::*;
+
     #[test]
     fn indent_of_samples() {
         for (content, position, max, expected) in [
@@ -137,8 +138,7 @@ mod test {
         preprocess(
             content,
             OnFailure::Continue,
-            &AdmonitionDefaults::default(),
-            &CustomDirectiveMap::default(),
+            &Overrides::default(),
             RenderTextMode::Html,
         )
         .unwrap()
@@ -596,10 +596,12 @@ Error rendering admonishment
 Failed with:
 
 ```log
-TOML parsing error: TOML parse error at line 1, column 8
+'title="' is not a valid directive or TOML key-value pair.
+
+TOML parsing error: TOML parse error at line 1, column 21
   |
-1 | title="
-  |        ^
+1 | config = { title=" }
+  |                     ^
 invalid basic string
 
 ```
@@ -631,8 +633,7 @@ Bonus content!
             preprocess(
                 content,
                 OnFailure::Bail,
-                &AdmonitionDefaults::default(),
-                &CustomDirectiveMap::default(),
+                &Overrides::default(),
                 RenderTextMode::Html
             )
             .unwrap_err()
@@ -659,8 +660,7 @@ x = 20;
             preprocess(
                 content,
                 OnFailure::Bail,
-                &AdmonitionDefaults::default(),
-                &CustomDirectiveMap::default(),
+                &Overrides::default(),
                 RenderTextMode::Strip
             )
             .unwrap(),
@@ -734,12 +734,14 @@ Text
         let preprocess_result = preprocess(
             content,
             OnFailure::Continue,
-            &AdmonitionDefaults {
-                title: Some("Admonish".to_owned()),
-                css_id_prefix: None,
-                collapsible: false,
+            &Overrides {
+                book: AdmonitionDefaults {
+                    title: Some("Admonish".to_owned()),
+                    css_id_prefix: None,
+                    collapsible: false,
+                },
+                ..Default::default()
             },
-            &CustomDirectiveMap::default(),
             RenderTextMode::Html,
         )
         .unwrap();
@@ -770,12 +772,14 @@ Text
         let preprocess_result = preprocess(
             content,
             OnFailure::Continue,
-            &AdmonitionDefaults {
-                title: Some("Admonish".to_owned()),
-                css_id_prefix: None,
-                collapsible: false,
+            &Overrides {
+                book: AdmonitionDefaults {
+                    title: Some("Admonish".to_owned()),
+                    css_id_prefix: None,
+                    collapsible: false,
+                },
+                ..Default::default()
             },
-            &CustomDirectiveMap::default(),
             RenderTextMode::Html,
         )
         .unwrap();
@@ -888,6 +892,39 @@ Check Mark
 
 A simple admonition.
 
+</div>
+</div>
+Text
+"##;
+
+        assert_eq!(expected, prep(content));
+    }
+
+    #[test]
+    fn title_and_content_with_html() {
+        // Note that we use toml literal (single quoted) strings here
+        // and the fact we have an equals sign in the value does not cause
+        // us to break (because we're using v3 syntax, not v2)
+        let content = r#"# Chapter
+```admonish success title='Check <span class="emphasis">Mark</span>'
+A <span class="emphasis">simple</span> admonition.
+```
+Text
+"#;
+
+        let expected = r##"# Chapter
+
+<div id="admonition-check-mark" class="admonition admonish-success">
+<div class="admonition-title">
+
+Check <span class="emphasis">Mark</span>
+
+<a class="admonition-anchor-link" href="#admonition-check-mark"></a>
+</div>
+<div>
+
+A <span class="emphasis">simple</span> admonition.
+
 </div>
 </div>
 Text
@@ -926,12 +963,14 @@ Text
         let preprocess_result = preprocess(
             content,
             OnFailure::Continue,
-            &AdmonitionDefaults {
-                title: Some("Info".to_owned()),
-                css_id_prefix: Some("".to_owned()),
-                collapsible: false,
+            &Overrides {
+                book: AdmonitionDefaults {
+                    title: Some("Info".to_owned()),
+                    css_id_prefix: Some("".to_owned()),
+                    collapsible: false,
+                },
+                ..Default::default()
             },
-            &CustomDirectiveMap::default(),
             RenderTextMode::Html,
         )
         .unwrap();
@@ -968,12 +1007,14 @@ Text
         let preprocess_result = preprocess(
             content,
             OnFailure::Continue,
-            &AdmonitionDefaults {
-                title: Some("Info".to_owned()),
-                css_id_prefix: Some("prefix-".to_owned()),
-                collapsible: false,
+            &Overrides {
+                book: AdmonitionDefaults {
+                    title: Some("Info".to_owned()),
+                    css_id_prefix: Some("prefix-".to_owned()),
+                    collapsible: false,
+                },
+                ..Default::default()
             },
-            &CustomDirectiveMap::default(),
             RenderTextMode::Html,
         )
         .unwrap();
@@ -1010,12 +1051,14 @@ Text
         let preprocess_result = preprocess(
             content,
             OnFailure::Continue,
-            &AdmonitionDefaults {
-                title: Some("Info".to_owned()),
-                css_id_prefix: Some("ignored-prefix-".to_owned()),
-                collapsible: false,
+            &Overrides {
+                book: AdmonitionDefaults {
+                    title: Some("Info".to_owned()),
+                    css_id_prefix: Some("ignored-prefix-".to_owned()),
+                    collapsible: false,
+                },
+                ..Default::default()
             },
-            &CustomDirectiveMap::default(),
             RenderTextMode::Html,
         )
         .unwrap();

src/parse.rs

@@ -5,7 +5,7 @@ use crate::{
     book_config::OnFailure,
     render::Admonition,
     resolve::AdmonitionMeta,
-    types::{AdmonitionDefaults, BuiltinDirective, CssId, CustomDirectiveMap},
+    types::{BuiltinDirective, CssId, Overrides},
 };
 
 /// Given the content in the span of the code block, and the info string,
@@ -19,8 +19,7 @@ use crate::{
 /// If the code block is not an admonition, return `None`.
 pub(crate) fn parse_admonition<'a>(
     info_string: &'a str,
-    admonition_defaults: &'a AdmonitionDefaults,
-    custom_directives: &'a CustomDirectiveMap,
+    overrides: &'a Overrides,
     content: &'a str,
     on_failure: OnFailure,
     indent: usize,
@@ -28,8 +27,7 @@ pub(crate) fn parse_admonition<'a>(
     // We need to know fence details anyway for error messages
     let extracted = extract_admonish_body(content);
 
-    let info =
-        AdmonitionMeta::from_info_string(info_string, admonition_defaults, custom_directives)?;
+    let info = AdmonitionMeta::from_info_string(info_string, overrides)?;
     let info = match info {
         Ok(info) => info,
         Err(message) => {

src/preprocessor.rs

@@ -8,7 +8,7 @@ use mdbook::{
 use crate::{
     book_config::{admonish_config_from_context, Config, RenderMode},
     markdown::preprocess,
-    types::{CustomDirectiveMap, RenderTextMode},
+    types::{Overrides, RenderTextMode},
 };
 
 pub struct Admonish;
@@ -22,11 +22,21 @@ impl Preprocessor for Admonish {
         let config = admonish_config_from_context(ctx)?;
         ensure_compatible_assets_version(&config)?;
 
-        let custom_directives =
-            CustomDirectiveMap::from_configs(config.custom.into_iter().map(Into::into));
+        let custom_directives = config
+            .directive
+            .custom
+            .into_iter()
+            .map(Into::into)
+            .collect();
         let on_failure = config.on_failure;
         let admonition_defaults = config.default;
 
+        let overrides = Overrides {
+            book: admonition_defaults,
+            custom: custom_directives,
+            builtin: config.directive.builtin,
+        };
+
         // Load what rendering we should do from config, falling back to a default
         let render_mode = config
             .renderer
@@ -55,16 +65,11 @@ impl Preprocessor for Admonish {
 
             if let BookItem::Chapter(ref mut chapter) = *item {
                 res = Some(
-                    preprocess(
-                        &chapter.content,
-                        on_failure,
-                        &admonition_defaults,
-                        &custom_directives,
-                        render_text_mode,
-                    )
-                    .map(|md| {
-                        chapter.content = md;
-                    }),
+                    preprocess(&chapter.content, on_failure, &overrides, render_text_mode).map(
+                        |md| {
+                            chapter.content = md;
+                        },
+                    ),
                 );
             }
         });

src/resolve.rs

@@ -1,7 +1,5 @@
 use crate::config::InstanceConfig;
-use crate::types::{
-    AdmonitionDefaults, BuiltinDirective, CssId, CustomDirective, CustomDirectiveMap,
-};
+use crate::types::{BuiltinDirective, CssId, CustomDirective, CustomDirectiveMap, Overrides};
 use std::fmt;
 use std::str::FromStr;
 
@@ -59,20 +57,15 @@ impl Directive {
 impl AdmonitionMeta {
     pub fn from_info_string(
         info_string: &str,
-        defaults: &AdmonitionDefaults,
-        custom_directives: &CustomDirectiveMap,
+        overrides: &Overrides,
     ) -> Option<Result<Self, String>> {
         InstanceConfig::from_info_string(info_string)
-            .map(|raw| raw.map(|raw| Self::resolve(raw, defaults, custom_directives)))
+            .map(|raw| raw.map(|raw| Self::resolve(raw, overrides)))
     }
 
     /// Combine the per-admonition configuration with global defaults (and
     /// other logic) to resolve the values needed for rendering.
-    fn resolve(
-        raw: InstanceConfig,
-        defaults: &AdmonitionDefaults,
-        custom_directives: &CustomDirectiveMap,
-    ) -> Self {
+    fn resolve(raw: InstanceConfig, overrides: &Overrides) -> Self {
         let InstanceConfig {
             directive: raw_directive,
             title,
@@ -82,10 +75,27 @@ impl AdmonitionMeta {
         } = raw;
 
         // Use values from block, else load default value
-        let title = title.or_else(|| defaults.title.clone());
-        let collapsible = collapsible.unwrap_or(defaults.collapsible);
+        let title = title.or_else(|| overrides.book.title.clone());
 
-        let directive = Directive::from_str(custom_directives, &raw_directive);
+        let directive = Directive::from_str(&overrides.custom, &raw_directive);
+
+        let collapsible = match directive {
+            // If the directive is a builin one, use collapsible from block, else use default
+            // value of the builtin directive, else use global default value
+            Ok(Directive::Builtin(directive)) => collapsible.unwrap_or(
+                overrides
+                    .builtin
+                    .get(&directive)
+                    .and_then(|config| config.collapsible)
+                    .unwrap_or(overrides.book.collapsible),
+            ),
+            // If the directive is a custom one, use collapsible from block, else use default
+            // value of the custom directive, else use global default value
+            Ok(Directive::Custom(ref custom_dir)) => {
+                collapsible.unwrap_or(custom_dir.collapsible.unwrap_or(overrides.book.collapsible))
+            }
+            Err(_) => collapsible.unwrap_or(overrides.book.collapsible),
+        };
 
         // Load the directive (and title, if one still not given)
         let (directive, title) = match (directive, title) {
@@ -100,7 +110,8 @@ impl AdmonitionMeta {
         } else {
             const DEFAULT_CSS_ID_PREFIX: &str = "admonition-";
             CssId::Prefix(
-                defaults
+                overrides
+                    .book
                     .css_id_prefix
                     .clone()
                     .unwrap_or_else(|| DEFAULT_CSS_ID_PREFIX.to_owned()),
@@ -141,6 +152,10 @@ fn uppercase_first(input: &str) -> String {
 
 #[cfg(test)]
 mod test {
+    use std::collections::HashMap;
+
+    use crate::types::{AdmonitionDefaults, BuiltinDirectiveConfig};
+
     use super::*;
     use pretty_assertions::assert_eq;
 
@@ -167,8 +182,7 @@ mod test {
                     additional_classnames: Vec::new(),
                     collapsible: None,
                 },
-                &Default::default(),
-                &CustomDirectiveMap::default(),
+                &Overrides::default(),
             ),
             AdmonitionMeta {
                 directive: "note".to_owned(),
@@ -191,12 +205,14 @@ mod test {
                     additional_classnames: Vec::new(),
                     collapsible: None,
                 },
-                &AdmonitionDefaults {
-                    title: Some("Important!!!".to_owned()),
-                    css_id_prefix: Some("custom-prefix-".to_owned()),
-                    collapsible: true,
-                },
-                &CustomDirectiveMap::default(),
+                &Overrides {
+                    book: AdmonitionDefaults {
+                        title: Some("Important!!!".to_owned()),
+                        css_id_prefix: Some("custom-prefix-".to_owned()),
+                        collapsible: true,
+                    },
+                    ..Default::default()
+                }
             ),
             AdmonitionMeta {
                 directive: "note".to_owned(),
@@ -219,12 +235,14 @@ mod test {
                     additional_classnames: Vec::new(),
                     collapsible: None,
                 },
-                &AdmonitionDefaults {
-                    title: Some("Important!!!".to_owned()),
-                    css_id_prefix: Some("ignored-custom-prefix-".to_owned()),
-                    collapsible: true,
-                },
-                &CustomDirectiveMap::default(),
+                &Overrides {
+                    book: AdmonitionDefaults {
+                        title: Some("Important!!!".to_owned()),
+                        css_id_prefix: Some("ignored-custom-prefix-".to_owned()),
+                        collapsible: true,
+                    },
+                    ..Default::default()
+                }
             ),
             AdmonitionMeta {
                 directive: "note".to_owned(),
@@ -247,12 +265,17 @@ mod test {
                     additional_classnames: Vec::new(),
                     collapsible: None,
                 },
-                &AdmonitionDefaults::default(),
-                &CustomDirectiveMap::from_configs(vec![CustomDirective {
-                    directive: "frog".to_owned(),
-                    aliases: Vec::new(),
-                    title: None,
-                }]),
+                &Overrides {
+                    custom: [CustomDirective {
+                        directive: "frog".to_owned(),
+                        aliases: Vec::new(),
+                        title: None,
+                        collapsible: None,
+                    }]
+                    .into_iter()
+                    .collect(),
+                    ..Default::default()
+                }
             ),
             AdmonitionMeta {
                 directive: "frog".to_owned(),
@@ -275,12 +298,17 @@ mod test {
                     additional_classnames: Vec::new(),
                     collapsible: None,
                 },
-                &AdmonitionDefaults::default(),
-                &CustomDirectiveMap::from_configs(vec![CustomDirective {
-                    directive: "frog".to_owned(),
-                    aliases: Vec::new(),
-                    title: Some("🏳️‍🌈".to_owned()),
-                }]),
+                &Overrides {
+                    custom: [CustomDirective {
+                        directive: "frog".to_owned(),
+                        aliases: Vec::new(),
+                        title: Some("🏳️‍🌈".to_owned()),
+                        collapsible: None,
+                    }]
+                    .into_iter()
+                    .collect(),
+                    ..Default::default()
+                }
             ),
             AdmonitionMeta {
                 directive: "frog".to_owned(),
@@ -303,12 +331,17 @@ mod test {
                     additional_classnames: Vec::new(),
                     collapsible: None,
                 },
-                &AdmonitionDefaults::default(),
-                &CustomDirectiveMap::from_configs(vec![CustomDirective {
-                    directive: "frog".to_owned(),
-                    aliases: vec!["newt".to_owned(), "toad".to_owned()],
-                    title: Some("🏳️‍🌈".to_owned()),
-                }]),
+                &Overrides {
+                    custom: [CustomDirective {
+                        directive: "frog".to_owned(),
+                        aliases: vec!["newt".to_owned(), "toad".to_owned()],
+                        title: Some("🏳️‍🌈".to_owned()),
+                        collapsible: None,
+                    }]
+                    .into_iter()
+                    .collect(),
+                    ..Default::default()
+                }
             ),
             AdmonitionMeta {
                 directive: "frog".to_owned(),
@@ -319,4 +352,109 @@ mod test {
             }
         );
     }
+
+    #[test]
+    fn test_admonition_info_from_raw_with_collapsible_custom_directive() {
+        assert_eq!(
+            AdmonitionMeta::resolve(
+                InstanceConfig {
+                    directive: "frog".to_owned(),
+                    title: None,
+                    id: None,
+                    additional_classnames: Vec::new(),
+                    collapsible: None,
+                },
+                &Overrides {
+                    custom: [CustomDirective {
+                        directive: "frog".to_owned(),
+                        aliases: Vec::new(),
+                        title: None,
+                        collapsible: Some(true),
+                    }]
+                    .into_iter()
+                    .collect(),
+                    ..Default::default()
+                }
+            ),
+            AdmonitionMeta {
+                directive: "frog".to_owned(),
+                title: "Frog".to_owned(),
+                css_id: CssId::Prefix("admonition-".to_owned()),
+                additional_classnames: Vec::new(),
+                collapsible: true,
+            }
+        );
+    }
+
+    #[test]
+    fn test_admonition_info_from_raw_with_collapsible_builtin_directive() {
+        assert_eq!(
+            AdmonitionMeta::resolve(
+                InstanceConfig {
+                    directive: "abstract".to_owned(),
+                    title: None,
+                    id: None,
+                    additional_classnames: Vec::new(),
+                    collapsible: None,
+                },
+                &Overrides {
+                    book: AdmonitionDefaults {
+                        title: None,
+                        css_id_prefix: None,
+                        collapsible: false,
+                    },
+                    builtin: HashMap::from([(
+                        BuiltinDirective::Abstract,
+                        BuiltinDirectiveConfig {
+                            collapsible: Some(true),
+                        }
+                    )]),
+                    ..Default::default()
+                }
+            ),
+            AdmonitionMeta {
+                directive: "abstract".to_owned(),
+                title: "Abstract".to_owned(),
+                css_id: CssId::Prefix("admonition-".to_owned()),
+                additional_classnames: Vec::new(),
+                collapsible: true,
+            }
+        );
+    }
+
+    #[test]
+    fn test_admonition_info_from_raw_with_non_collapsible_builtin_directive() {
+        assert_eq!(
+            AdmonitionMeta::resolve(
+                InstanceConfig {
+                    directive: "abstract".to_owned(),
+                    title: None,
+                    id: None,
+                    additional_classnames: Vec::new(),
+                    collapsible: None,
+                },
+                &Overrides {
+                    book: AdmonitionDefaults {
+                        title: None,
+                        css_id_prefix: None,
+                        collapsible: true,
+                    },
+                    builtin: HashMap::from([(
+                        BuiltinDirective::Abstract,
+                        BuiltinDirectiveConfig {
+                            collapsible: Some(false),
+                        }
+                    )]),
+                    ..Default::default()
+                }
+            ),
+            AdmonitionMeta {
+                directive: "abstract".to_owned(),
+                title: "Abstract".to_owned(),
+                css_id: CssId::Prefix("admonition-".to_owned()),
+                additional_classnames: Vec::new(),
+                collapsible: false,
+            }
+        );
+    }
 }

src/types.rs

@@ -24,7 +24,8 @@ pub(crate) struct AdmonitionDefaults {
 /// These are guaranteed to have valid CSS/icons available.
 ///
 /// Custom directives can also be added via the book.toml config.
-#[derive(Debug, PartialEq)]
+#[derive(Debug, PartialEq, Clone, Copy, Eq, Deserialize, Serialize, Hash)]
+#[serde(rename_all = "lowercase")]
 pub(crate) enum BuiltinDirective {
     Note,
     Abstract,
@@ -85,25 +86,27 @@ impl fmt::Display for BuiltinDirective {
 /// The subset of information we care about during plugin runtime for custom directives.
 ///
 /// This drops information only needed during CSS generation.
-#[derive(Clone)]
+#[derive(Debug, Clone)]
 pub(crate) struct CustomDirective {
     pub directive: String,
     pub aliases: Vec<String>,
     pub title: Option<String>,
+    pub collapsible: Option<bool>,
 }
 
-impl From<crate::book_config::CustomDirective> for CustomDirective {
-    fn from(other: crate::book_config::CustomDirective) -> Self {
+impl From<(String, crate::book_config::CustomDirective)> for CustomDirective {
+    fn from((directive, config): (String, crate::book_config::CustomDirective)) -> Self {
         let crate::book_config::CustomDirective {
-            directive,
             aliases,
             title,
+            collapsible,
             ..
-        } = other;
+        } = config;
         Self {
             directive,
             aliases,
             title,
+            collapsible,
         }
     }
 }
@@ -114,7 +117,7 @@ impl From<crate::book_config::CustomDirective> for CustomDirective {
 /// and returns the output-directive config.
 ///
 /// i.e. this is the step alias mapping happens at
-#[derive(Default)]
+#[derive(Debug, Clone, Default)]
 pub(crate) struct CustomDirectiveMap {
     inner: HashMap<String, CustomDirective>,
 }
@@ -123,19 +126,18 @@ impl CustomDirectiveMap {
     pub fn get(&self, key: &str) -> Option<&CustomDirective> {
         self.inner.get(key)
     }
+}
 
-    pub fn from_configs<T>(configs: T) -> Self
-    where
-        T: IntoIterator<Item = CustomDirective>,
-    {
+impl FromIterator<CustomDirective> for CustomDirectiveMap {
+    fn from_iter<I: IntoIterator<Item = CustomDirective>>(iter: I) -> Self {
         let mut inner = HashMap::default();
-        for directive in configs.into_iter() {
+        for config in iter.into_iter() {
             inner
-                .entry(directive.directive.clone())
-                .or_insert(directive.clone());
+                .entry(config.directive.clone())
+                .or_insert(config.clone());
 
-            for alias in directive.aliases.iter() {
-                inner.entry(alias.clone()).or_insert(directive.clone());
+            for alias in config.aliases.iter() {
+                inner.entry(alias.clone()).or_insert(config.clone());
             }
         }
 
@@ -143,6 +145,13 @@ impl CustomDirectiveMap {
     }
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+pub(crate) struct BuiltinDirectiveConfig {
+    /// Default collapsible value.
+    #[serde(default)]
+    pub collapsible: Option<bool>,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum RenderTextMode {
     Strip,
@@ -160,3 +169,10 @@ pub(crate) enum CssId {
     /// will generate the rest of the id based on the title
     Prefix(String),
 }
+
+#[derive(Debug, Clone, Default)]
+pub(crate) struct Overrides {
+    pub book: AdmonitionDefaults,
+    pub builtin: HashMap<BuiltinDirective, BuiltinDirectiveConfig>,
+    pub custom: CustomDirectiveMap,
+}

v2.md

@@ -0,0 +1,13 @@
+# v2 Notes
+
+## Compatibility to drop
+
+- v1 config loading system from block info strings
+- v2 config loading system from block info strings
+- Support for `custom` configuration, moved to `directive.custom`
+- `css-id-prefix` kebab case
+
+## Wishlist
+
+- `mdbook` not to use a broken version of `toml` in the public api
+- `mdbook` to support loading css files from plugins