From 65dae11e470450bddbe8451e7c3b5d27ca01f30a Mon Sep 17 00:00:00 2001
From: Michael Howell <michael@notriddle.com>
Date: Fri, 8 Sep 2023 13:14:54 -0700
Subject: [PATCH 1/2] Add `.warning` class for doc author use

This is designed to be compatible with rustdoc's version, in
https://github.com/rust-lang/rust/pull/106561
---
 guide/src/format/mdbook.md  | 26 ++++++++++++++++++++++++++
 src/theme/css/general.css   | 23 +++++++++++++++++++++++
 src/theme/css/variables.css | 12 ++++++++++++
 3 files changed, 61 insertions(+)

diff --git a/guide/src/format/mdbook.md b/guide/src/format/mdbook.md
index 2872b250..15b8d1a7 100644
--- a/guide/src/format/mdbook.md
+++ b/guide/src/format/mdbook.md
@@ -314,3 +314,29 @@ contents (sidebar) by including a `\{{#title ...}}` near the top of the page.
 ```hbs
 \{{#title My Title}}
 ```
+
+## HTML classes provided by mdBook
+
+The `class="warning"` can be applied to make a warning, or similar note, stand out.
+
+```html
+<div class="warning">
+
+This is a bad thing that you should pay attention to.
+
+Warning blocks should be used sparingly in documentation, to avoid "warning
+fatique," where people are trained to ignore them because they usually don't
+matter for what they're doing.
+
+</div>
+```
+
+<div class="warning">
+
+This is a bad thing that you should pay attention to.
+
+Warning blocks should be used sparingly in documentation, to avoid "warning
+fatique," where people are trained to ignore them because they usually don't
+matter for what they're doing.
+
+</div>
diff --git a/src/theme/css/general.css b/src/theme/css/general.css
index 7e746d27..e7d20da7 100644
--- a/src/theme/css/general.css
+++ b/src/theme/css/general.css
@@ -156,6 +156,29 @@ blockquote {
     border-block-end: .1em solid var(--quote-border);
 }
 
+.warning {
+    margin: 20px;
+    padding: 0 20px;
+    border-inline-start: 2px solid var(--warning-border);
+}
+
+.warning:before {
+    position: absolute;
+    width: 3rem;
+    height: 3rem;
+    margin-inline-start: calc(-1.5rem - 21px);
+    content: "ⓘ";
+    text-align: center;
+    background-color: var(--bg);
+    color: var(--warning-border);
+    font-weight: bold;
+    font-size: 2rem;
+}
+
+blockquote .warning:before {
+    background-color: var(--quote-bg);
+}
+
 kbd {
     background-color: var(--table-border-color);
     border-radius: 4px;
diff --git a/src/theme/css/variables.css b/src/theme/css/variables.css
index 59fcda88..10a75909 100644
--- a/src/theme/css/variables.css
+++ b/src/theme/css/variables.css
@@ -38,6 +38,8 @@
     --quote-bg: hsl(226, 15%, 17%);
     --quote-border: hsl(226, 15%, 22%);
 
+    --warning-border: #ff8e00;
+
     --table-border-color: hsl(210, 25%, 13%);
     --table-header-bg: hsl(210, 25%, 28%);
     --table-alternate-bg: hsl(210, 25%, 11%);
@@ -80,6 +82,8 @@
     --quote-bg: hsl(234, 21%, 18%);
     --quote-border: hsl(234, 21%, 23%);
 
+    --warning-border: #ff8e00;
+
     --table-border-color: hsl(200, 7%, 13%);
     --table-header-bg: hsl(200, 7%, 28%);
     --table-alternate-bg: hsl(200, 7%, 11%);
@@ -122,6 +126,8 @@
     --quote-bg: hsl(197, 37%, 96%);
     --quote-border: hsl(197, 37%, 91%);
 
+    --warning-border: #ff8e00;
+
     --table-border-color: hsl(0, 0%, 95%);
     --table-header-bg: hsl(0, 0%, 80%);
     --table-alternate-bg: hsl(0, 0%, 97%);
@@ -164,6 +170,8 @@
     --quote-bg: hsl(226, 15%, 17%);
     --quote-border: hsl(226, 15%, 22%);
 
+    --warning-border: #ff8e00;
+
     --table-border-color: hsl(226, 23%, 16%);
     --table-header-bg: hsl(226, 23%, 31%);
     --table-alternate-bg: hsl(226, 23%, 14%);
@@ -206,6 +214,8 @@
     --quote-bg: hsl(60, 5%, 75%);
     --quote-border: hsl(60, 5%, 70%);
 
+    --warning-border: #ff8e00;
+
     --table-border-color: hsl(60, 9%, 82%);
     --table-header-bg: #b3a497;
     --table-alternate-bg: hsl(60, 9%, 84%);
@@ -249,6 +259,8 @@
         --quote-bg: hsl(234, 21%, 18%);
         --quote-border: hsl(234, 21%, 23%);
 
+        --warning-border: #ff8e00;
+
         --table-border-color: hsl(200, 7%, 13%);
         --table-header-bg: hsl(200, 7%, 28%);
         --table-alternate-bg: hsl(200, 7%, 11%);

From ceb8b509e2ce0646f94a5e3e910508fdef1cfc00 Mon Sep 17 00:00:00 2001
From: Michael Howell <michael@notriddle.com>
Date: Fri, 8 Sep 2023 13:27:02 -0700
Subject: [PATCH 2/2] Add more guides to stock CSS classes

---
 guide/src/format/mdbook.md | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/guide/src/format/mdbook.md b/guide/src/format/mdbook.md
index 15b8d1a7..45fb506a 100644
--- a/guide/src/format/mdbook.md
+++ b/guide/src/format/mdbook.md
@@ -317,7 +317,29 @@ contents (sidebar) by including a `\{{#title ...}}` near the top of the page.
 
 ## HTML classes provided by mdBook
 
-The `class="warning"` can be applied to make a warning, or similar note, stand out.
+<img class="right" src="images/rust-logo-blk.svg" alt="The Rust logo">
+
+### `class="left"` and `"right"`
+
+These classes are provided by default, for inline HTML to float images.
+
+```html
+<img class="right" src="images/rust-logo-blk.svg" alt="The Rust logo">
+```
+
+### `class="hidden"`
+
+HTML tags with class `hidden` will not be shown.
+
+```html
+<div class="hidden">This will not be seen.</div>
+```
+
+<div class="hidden">This will not be seen.</div>
+
+### `class="warning"`
+
+To make a warning or similar note stand out, wrap it in a warning div.
 
 ```html
 <div class="warning">