Rework admonition rendering.

This changes the admonitions to render pretty much the same way that
GitHub does it.

Author: ehuss

docs/authoring.md

@@ -167,9 +167,12 @@ Admonitions use a style similar to GitHub-flavored markdown, where the style nam
 ```markdown
 > [!WARNING]
 > This is a warning.
+
+> [!NOTE]
+> This is a note.
 ```
 
-All this does is apply a CSS class to the blockquote. You should define the color or style of the rule in the [`theme/reference.css`](https://github.com/rust-lang/reference/blob/master/theme/reference.css) file if it isn't already defined.
+The color and styling is defined in [`theme/reference.css`](https://github.com/rust-lang/reference/blob/master/theme/reference.css) and the transformation and icons are in [`mdbook-spec/src/lib.rs`](https://github.com/rust-lang/reference/blob/HEAD/mdbook-spec/src/lib.rs).
 
 ## Style
 

mdbook-spec/src/lib.rs

@@ -144,22 +144,38 @@ impl Spec {
     /// > ...
     /// ```
     ///
-    /// This will add a `<div class="warning">` around the blockquote so that
-    /// it can be styled differently. Any text between the brackets that can
-    /// be a CSS class is valid. The actual styling needs to be added in a CSS
-    /// file.
-    fn admonitions(&self, chapter: &Chapter) -> String {
+    /// This will add a `<div class="alert alert-warning">` 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.
+    fn admonitions(&self, chapter: &Chapter, diag: &mut Diagnostics) -> String {
         ADMONITION_RE
             .replace_all(&chapter.content, |caps: &Captures<'_>| {
                 let lower = caps["admon"].to_lowercase();
                 let term = to_initial_case(&caps["admon"]);
                 let blockquote = &caps["blockquote"];
                 let initial_spaces = blockquote.chars().position(|ch| ch != ' ').unwrap_or(0);
                 let space = &blockquote[..initial_spaces];
+                // These icons are from GitHub, MIT License, see https://github.com/primer/octicons
+                let svg = match lower.as_str() {
+                    "note" => "<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>",
+                    "warning" => "<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>",
+                    _ => {
+                        warn_or_err!(
+                            diag,
+                            "admonition `{lower}` in {:?} is incorrect or not yet supported",
+                            chapter.path.as_ref().unwrap()
+                        );
+                        ""
+                    }
+                };
                 format!(
-                    "{space}<div class=\"{lower}\">\n\
+                    "{space}<div class=\"alert alert-{lower}\">\n\
                     \n\
-                    {space}> ***{term}:***\n\
+                    {space}> <p class=\"alert-title\">\
+                        <svg viewBox=\"0 0 16 16\" width=\"18\" height=\"18\">\
+                            {svg}\
+                        </svg>{term}</p>\n\
+                    {space} >\n\
                     {blockquote}\n\
                     \n\
                     {space}</div>\n",
@@ -226,7 +242,7 @@ impl Preprocessor for Spec {
             if ch.is_draft_chapter() {
                 return;
             }
-            ch.content = self.admonitions(&ch);
+            ch.content = self.admonitions(&ch, &mut diag);
             ch.content = self.auto_link_references(&ch, &rules);
             ch.content = self.render_rule_definitions(&ch.content, &tests, &git_ref);
             if ch.name == "Test summary" {

theme/reference.css

@@ -11,47 +11,81 @@ the parenthetical. So for this example, you'd use
 }
 
 /*
-Warnings are defined using admonitions in blockquotes:
+Admonitions are defined with blockquotes:
 
 > [!WARNING]
 > This is bad!
 
+See mdbook-spec/src/lib.rs.
 */
-main .warning blockquote {
-    padding: 0px;
-}
-
-main .warning blockquote p {
-    padding: 0px 20px;
+.alert blockquote {
+    /* 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. */
+    border-inline-start-style: solid;
+    border-inline-start-width: 4px;
+    /* Disable the background color from mdbook for a cleaner look. */
+    background-color: inherit;
+    /* 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;
 }
 
-main .warning blockquote p:first-child::before {
-    content: "⚠️ ";
+.alert-title {
+    /* Slightly increase the weight for more emphasis. */
+    font-weight: 600;
+    /* Vertically center the icon with the text. */
+    display: flex;
+    align-items: center;
+    /* Remove default large margins for a more compact display.
+       Important to override .alert p rule. */
+    margin: 0 0 8px 0 !important;
 }
-
-.light main .warning blockquote,
-.rust main .warning blockquote {
-    border: 2px solid red;
-    background: #ffcece;
+.alert blockquote > :nth-child(2) {
+    /* Default margins of content just below the label add too much space. */
+    margin-top: 0;
 }
-
-.rust main .warning blockquote {
-    /* overrides previous declaration */
-    border-color: #961717;
+.alert blockquote > :last-child {
+    /* Default margins of content add too much space. */
+    margin-bottom: 0;
 }
 
-.coal main .warning blockquote,
-.navy main .warning blockquote,
-.ayu main .warning blockquote {
-    background: #542626;
+.alert-title svg {
+    fill: currentColor;
+    /* Add some space between the icon and the text. */
+    margin-right: 8px;
 }
 
-/* Make the links higher contrast on dark themes */
-.coal main .warning blockquote p a,
-.navy main .warning blockquote p a,
-.ayu main .warning blockquote p a {
-    color: #80d0d0;
+.light .alert {
+    --alert-note-color: #0969da;
+    --alert-warning-color: #9a6700;
+}
+.ayu .alert {
+    --alert-note-color: #74b9ff;
+    --alert-warning-color: #f0b72f;
+}
+.rust .alert {
+    --alert-note-color: #023b95;
+    --alert-warning-color: #603700;
+}
+.coal .alert,
+.navy .alert {
+    --alert-note-color: #4493f8;
+    --alert-warning-color: #d29922;
+}
+.alert-note blockquote {
+    border-inline-start-color: var(--alert-note-color);
+}
+.alert-warning blockquote {
+    border-inline-start-color: var(--alert-warning-color);
+}
+.alert-note .alert-title {
+    color: var(--alert-note-color);
+}
+.alert-warning .alert-title {
+    color: var(--alert-warning-color);
 }
 
 /* <kbd> tags can be used to highlight specific character elements. */