rust-lang · DanielEScherzer · Apr 19, 2026
diff --git a/theme/reference.css b/theme/reference.css
@@ -11,15 +11,11 @@
     --railroad-rect-fill: hsl(-290, 70%, 90%);
 }
 .light {
-    --alert-note-color: #0969da;
-    --alert-warning-color: #9a6700;
     --alert-edition-color: #1a7f37;
     --alert-example-color: #8250df;
     --grammar-literal-bg: #fafafa;
 }
 .rust {
-    --alert-note-color: #023b95;
-    --alert-warning-color: #603700;
     --alert-edition-color: #008200;
     --alert-example-color: #8250df;
     --grammar-literal-bg: #dedede;
@@ -29,15 +25,11 @@
     --inline-code-color: var(--grammar-comment-color);
 }
 .coal, .navy {
-    --alert-note-color: #4493f8;
-    --alert-warning-color: #d29922;
     --alert-edition-color: #3fb950;
     --alert-example-color: #ab7df8;
     --grammar-literal-bg: #1d1f21;
 }
 .ayu {
-    --alert-note-color: #74b9ff;
-    --alert-warning-color: #f0b72f;
     --alert-edition-color: #2bd853;
     --alert-example-color: #d3abff;
     --grammar-literal-bg: #191f26;
@@ -68,12 +60,18 @@ the parenthetical. So for this example, you'd use
 /*
 Admonitions are defined with blockquotes:
 
-> [!WARNING]
+> [!EXAMPLE]
 > This is bad!
 
-See tools/mdbook-spec/src/admonitions.rs.
+The admonitions from tools/mdbook-spec/src/admonitions.rs are custom ones for
+the reference (e.g. examples), upstream mdbook also provides some (like for
+`[!WARNING]`, use consistent styles for both).
+
+Some of the styles specified below for the upstream admonitions already match
+the upstream styles but are included for consistency.
 */
-.alert blockquote {
+.alert blockquote,
+blockquote.blockquote-tag {
     /* Add some padding to make the vertical bar a little taller than the text.*/
     padding: 8px 0px 8px 20px;
     /* Add a solid color bar on the left side. */
@@ -84,54 +82,40 @@ See tools/mdbook-spec/src/admonitions.rs.
     /* Disable border blocks from mdbook. */
     border-block-start: none;
     border-block-end: none;
-    /* Reduce margin from mdbook, it uses a lot of space. */
-    margin: 10px 0;
+    /* Reduce margin from mdbook, it uses a lot of space.
+      Important to override `main > ul > li > *:last-child` rule. */
+    margin: 10px 0 !important;
 }
 
-.alert-title {
-    /* Slightly increase the weight for more emphasis. */
-    font-weight: 600;
-    /* Vertically center the icon with the text. */
-    display: flex;
-    align-items: center;
+.blockquote-tag-title {
     /* Remove default large margins for a more compact display.
        Important to override .alert p rule. */
     margin: 0 0 8px 0 !important;
 }
-.alert blockquote > :nth-child(2) {
+.alert blockquote > :nth-child(2),
+blockquote.blockquote-tag > :nth-child(2) {
     /* Default margins of content just below the label add too much space. */
     margin-top: 0;
 }
-.alert blockquote > :last-child {
+.alert blockquote > :last-child,
+blockquote.blockquote-tag > :last-child {
     /* Default margins of content add too much space. */
     margin-bottom: 0;
 }
 
-.alert-title svg {
+.blockquote-tag-title svg {
     fill: currentColor;
     /* Add some space between the icon and the text. */
     margin-right: 8px;
 }
 
-.alert-note blockquote {
-    border-inline-start-color: var(--alert-note-color);
-}
-.alert-warning blockquote {
-    border-inline-start-color: var(--alert-warning-color);
-}
 .alert-edition blockquote {
     border-inline-start-color: var(--alert-edition-color);
 }
 .alert-example blockquote {
     border-inline-start-color: var(--alert-example-color);
 }
-.alert-note .alert-title {
-    color: var(--alert-note-color);
-}
-.alert-warning .alert-title {
-    color: var(--alert-warning-color);
-}
-.alert-edition .alert-title {
+.alert-edition .blockquote-tag-title {
     color: var(--alert-edition-color);
 }
 /* Puts a rounded rectangle around the edition date. */
@@ -143,7 +127,7 @@ See tools/mdbook-spec/src/admonitions.rs.
     font-weight: bold;
     color: var(--alert-edition-color);
 }
-.alert-example .alert-title {
+.alert-example .blockquote-tag-title {
     color: var(--alert-example-color);
 }
 

diff --git a/tools/mdbook-spec/src/admonitions.rs b/tools/mdbook-spec/src/admonitions.rs
@@ -15,17 +15,11 @@ use regex::{Captures, Regex};
 use std::sync::LazyLock;
 
 /// The Regex for the syntax for blockquotes that have a specific CSS class,
-/// like `> [!WARNING]`.
+/// like `> [!EXAMPLE]`.
 static ADMONITION_RE: LazyLock<Regex> = LazyLock::new(|| {
     Regex::new(r"(?m)^ *> \[!(?<admon>[^]]+)\]\n(?<blockquote>(?: *>.*\n)+)").unwrap()
 });
 
-// This icon is from GitHub, MIT License, see https://github.com/primer/octicons
-const ICON_NOTE: &str = r#"<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path>"#;
-
-// This icon is from GitHub, MIT License, see https://github.com/primer/octicons
-const ICON_WARNING: &str = r#"<path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path>"#;
-
 // This icon is from GitHub, MIT License, see https://github.com/primer/octicons
 const ICON_EXAMPLE: &str = r#"<path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path>"#;
 
@@ -34,11 +28,11 @@ const ICON_EXAMPLE: &str = r#"<path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a
 /// The blockquote should look something like:
 ///
 /// ```markdown
-/// > [!WARNING]
+/// > [!EXAMPLE]
 /// > ...
 /// ```
 ///
-/// This will add a `<div class="alert alert-warning">` around the
+/// This will add a `<div class="alert alert-example">` around the
 /// blockquote so that it can be styled differently, and injects an icon.
 /// The actual styling needs to be added in the `reference.css` CSS file.
 pub fn admonitions(chapter: &Chapter, diag: &mut Diagnostics) -> String {
@@ -54,7 +48,7 @@ pub fn admonitions(chapter: &Chapter, diag: &mut Diagnostics) -> String {
                 format!(
                     "{space}<div class=\"alert alert-{class}\">\n\
                     \n\
-                    {space}> <p class=\"alert-title\">\
+                    {space}> <p class=\"blockquote-tag-title\">\
                         {content}</p>\n\
                     {space} >\n\
                     {blockquote}\n\
@@ -73,9 +67,13 @@ pub fn admonitions(chapter: &Chapter, diag: &mut Diagnostics) -> String {
                 );
             }
 
+            match lower.as_str() {
+                "note" => return caps[0].to_string(),
+                "warning" => return caps[0].to_string(),
+                _ => (),
+            };
+
             let svg = match lower.as_str() {
-                "note" => ICON_NOTE,
-                "warning" => ICON_WARNING,
                 "example" => ICON_EXAMPLE,
                 _ => {
                     warn_or_err!(

diff --git a/tools/mdbook-spec/src/std_links.rs b/tools/mdbook-spec/src/std_links.rs
@@ -311,6 +311,16 @@ fn compute_replacements<'a>(
     for (url, link) in urls.iter().zip(links) {
         let Some(cap) = ANCHOR_URL.captures(url) else {
             let line = super::line_from_range(&chapter.content, &link.range);
+            // `[!NOTE]` and `[!WARNING]` will be handled by the admonitions
+            // support upstream
+            let initial_spaces = line.chars().position(|ch| ch != ' ').unwrap_or(0);
+            let after_spaces = &line[initial_spaces..];
+            if after_spaces == "> [!NOTE]" {
+                continue;
+            }
+            if after_spaces == "> [!WARNING]" {
+                continue;
+            }
             warn_or_err!(
                 diag,
                 "broken markdown link found in {}\n\