Custom ids

- You can now set custom CSS ids for admonishment blocks with the `id` field. - You can now customize the default CSS id prefix (default is `"admonition-"`).
tommilligan · Oct 24, 2023 · ea53b0d · ea53b0d
1 parent 31d5a27
commit ea53b0d
Show file tree

Hide file tree

Showing 12 changed files with 366 additions and 23 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1 +1,2 @@
-/target
+/target/
+/.idea/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- You can now set custom CSS ids for admonishment blocks with the `id` field.
+- You can now customize the default CSS id prefix (default is `"admonition-"`).
+
 ## 1.13.1
 
 ### Changed

diff --git a/book/src/overview.md b/book/src/overview.md
@@ -161,6 +161,23 @@ Will yield something like the following HTML, which you can then apply styles to
 </div>
 ```
 
+#### Custom CSS ID
+
+If you want to customize the CSS `id` field, set `id="custom-id"`.
+This will ignore [`default.css-id-prefix`](reference.md#default).
+
+The default id is a normalized version of the admonishment's title,
+prefixed with the `default.css-id-prefix`,
+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"
+Link to this block with `#my-special-info` instead of the default `#admonition-my-info`.
+```
+````
+
 #### Collapsible
 
 For a block to be initially collapsible, and then be openable, set `collapsible=true`:
@@ -176,3 +193,4 @@ Will yield something like the following HTML, which you can then apply styles to
 ```admonish collapsible=true
 Content will be hidden initially.
 ```
+
diff --git a/book/src/reference.md b/book/src/reference.md
@@ -38,6 +38,7 @@ Subfields:
 
 - `default.title` (optional): Title to use for blocks. Defaults to the directive used in titlecase.
 - `default.collapsible` (optional, default: `false`): Make blocks collapsible by default when set to `true`.
+- `default.css-id-prefix` (optional, default: `"admonition-"`): The default css id prefix to add to the id of all blocks. Ignored on blocks with an `id` field.
 
 ### `renderer`
 

diff --git a/src/config/mod.rs b/src/config/mod.rs
@@ -9,6 +9,7 @@ mod v2;
 pub(crate) struct InstanceConfig {
     pub(crate) directive: String,
     pub(crate) title: Option<String>,
+    pub(crate) id: Option<String>,
     pub(crate) additional_classnames: Vec<String>,
     pub(crate) collapsible: Option<bool>,
 }
@@ -69,18 +70,22 @@ mod test {
             InstanceConfig {
                 directive: "note".to_owned(),
                 title: None,
+                id: None,
                 additional_classnames: vec!["additional-classname".to_owned()],
                 collapsible: None,
             }
         );
         // v2 syntax is supported
         assert_eq!(
-            InstanceConfig::from_info_string(r#"admonish title="Custom Title" type="question""#)
-                .unwrap()
-                .unwrap(),
+            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,
             }

diff --git a/src/config/v1.rs b/src/config/v1.rs
@@ -52,6 +52,7 @@ pub(crate) fn from_config_string(config_string: &str) -> Result<InstanceConfig,
     Ok(InstanceConfig {
         directive: directive.to_owned(),
         title,
+        id: None,
         additional_classnames,
         collapsible: None,
     })
@@ -69,6 +70,7 @@ mod test {
             InstanceConfig {
                 directive: "".to_owned(),
                 title: None,
+                id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
             }
@@ -78,6 +80,7 @@ mod test {
             InstanceConfig {
                 directive: "".to_owned(),
                 title: None,
+                id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
             }
@@ -87,6 +90,7 @@ mod test {
             InstanceConfig {
                 directive: "unknown".to_owned(),
                 title: None,
+                id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
             }
@@ -96,6 +100,7 @@ mod test {
             InstanceConfig {
                 directive: "note".to_owned(),
                 title: None,
+                id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
             }
@@ -105,6 +110,7 @@ mod test {
             InstanceConfig {
                 directive: "note".to_owned(),
                 title: None,
+                id: None,
                 additional_classnames: vec!["additional-classname".to_owned()],
                 collapsible: None,
             }

diff --git a/src/config/v2.rs b/src/config/v2.rs
@@ -10,6 +10,8 @@ struct UserInput {
     #[serde(default)]
     title: Option<String>,
     #[serde(default)]
+    id: Option<String>,
+    #[serde(default)]
     class: Option<String>,
     #[serde(default)]
     collapsible: Option<bool>,
@@ -88,6 +90,7 @@ pub(crate) fn from_config_string(config_string: &str) -> Result<InstanceConfig,
     Ok(InstanceConfig {
         directive: config.r#type.unwrap_or_default(),
         title: config.title,
+        id: config.id,
         additional_classnames,
         collapsible: config.collapsible,
     })
@@ -105,6 +108,7 @@ mod test {
             InstanceConfig {
                 directive: "".to_owned(),
                 title: None,
+                id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
             }
@@ -114,6 +118,7 @@ mod test {
             InstanceConfig {
                 directive: "".to_owned(),
                 title: None,
+                id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
             }
@@ -126,6 +131,7 @@ mod test {
             InstanceConfig {
                 directive: "note".to_owned(),
                 title: Some("Никита".to_owned()),
+                id: None,
                 additional_classnames: vec!["additional".to_owned(), "classname".to_owned()],
                 collapsible: Some(true),
             }
@@ -136,6 +142,7 @@ mod test {
             InstanceConfig {
                 directive: "".to_owned(),
                 title: None,
+                id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
             }
@@ -146,6 +153,7 @@ mod test {
             InstanceConfig {
                 directive: "info".to_owned(),
                 title: None,
+                id: None,
                 additional_classnames: Vec::new(),
                 collapsible: None,
             }
@@ -156,10 +164,22 @@ mod test {
             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(),
+            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());
     }