Add an example admonition

This allows writing `> [!EXAMPLE]` to place an example in a block.

Author: ehuss

docs/authoring.md

@@ -180,6 +180,9 @@ Admonitions use a style similar to GitHub-flavored markdown, where the style nam
 
 > [!NOTE]
 > This is a note.
+
+> [!EXAMPLE]
+> This is an example.
 ```
 
 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/admonitions.rs`](https://github.com/rust-lang/reference/blob/HEAD/mdbook-spec/src/admonitions.rs).

mdbook-spec/src/admonitions.rs

@@ -17,6 +17,9 @@ const ICON_NOTE: &str = r#"<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5
 // 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="M 5.0693987,1.2383101 11.496127,7.665038 a 0.47311013,0.47311013 0 0 1 0,0.669924 L 5.0693987,14.76169 A 0.47311013,0.47311013 0 0 1 4.2613266,14.426728 V 1.573272 A 0.47311013,0.47311013 0 0 1 5.0693987,1.2383101 Z"></path>"#;
+
 /// Converts blockquotes with special headers into admonitions.
 ///
 /// The blockquote should look something like:
@@ -64,6 +67,7 @@ pub fn admonitions(chapter: &Chapter, diag: &mut Diagnostics) -> String {
             let svg = match lower.as_str() {
                 "note" => ICON_NOTE,
                 "warning" => ICON_WARNING,
+                "example" => ICON_EXAMPLE,
                 _ => {
                     warn_or_err!(
                         diag,

src/introduction.md

@@ -78,6 +78,14 @@ These conventions are documented here.
   > [!NOTE]
   > This is an example note.
 
+* Example blocks show an example that demonstrates some rule or points out some interesting aspect. Some examples may have hidden lines which can be viewed by clicking the eye icon that appears when hovering or tapping the example.
+
+  > [!EXAMPLE]
+  > This is a code example.
+  > ```rust
+  > println!("hello world");
+  > ```
+
 * Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box.
 
   > [!WARNING]

theme/reference.css

@@ -62,22 +62,26 @@ See mdbook-spec/src/admonitions.rs.
     --alert-note-color: #0969da;
     --alert-warning-color: #9a6700;
     --alert-edition-color: #1a7f37;
+    --alert-example-color: #8250df;
 }
 .ayu .alert {
     --alert-note-color: #74b9ff;
     --alert-warning-color: #f0b72f;
     --alert-edition-color: #2bd853;
+    --alert-example-color: #d3abff;
 }
 .rust .alert {
     --alert-note-color: #023b95;
     --alert-warning-color: #603700;
     --alert-edition-color: #008200;
+    --alert-example-color: #8250df;
 }
 .coal .alert,
 .navy .alert {
     --alert-note-color: #4493f8;
     --alert-warning-color: #d29922;
     --alert-edition-color: #3fb950;
+    --alert-example-color: #ab7df8;
 }
 .alert-note blockquote {
     border-inline-start-color: var(--alert-note-color);
@@ -88,6 +92,9 @@ See mdbook-spec/src/admonitions.rs.
 .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);
 }
@@ -106,6 +113,9 @@ See mdbook-spec/src/admonitions.rs.
     font-weight: bold;
     color: var(--alert-edition-color);
 }
+.alert-example .alert-title {
+    color: var(--alert-example-color);
+}
 
 /* <kbd> tags can be used to highlight specific character elements. */
 kbd {