Migrate admonitions to blockquote alerts (#5285)

jesserockz · web-flow · commit 301d6246ea77 · 2025-08-26T09:48:33.000+12:00
diff --git a/README.md b/README.md
@@ -188,17 +188,6 @@ Creates a component card with an image, title, and optional description that lin
   
 ```
 
-### `note`
-
-Creates a note admonition box to highlight important information.
-
-``` text
-{{< note >}}
-This is important information that the reader should pay attention to.
-You can include **Markdown** formatting within the note.
-{{< /note >}}
-```
-
 ### `seo`
 
 Adds SEO metadata tags to the page for better search engine optimization and social media sharing.
@@ -207,28 +196,6 @@ Adds SEO metadata tags to the page for better search engine optimization and soc
 {{< seo description="Detailed guide for setting up the DHT sensor with ESPHome" image="dht-sensor.jpg" >}}
 ```
 
-### `tip`
-
-Creates a tip admonition box to highlight helpful advice or best practices.
-
-``` text
-{{< tip >}}
-For best results, place the sensor away from heat sources.
-You can include **Markdown** formatting within the tip.
-{{< /tip >}}
-```
-
-### `warning`
-
-Creates a warning admonition box to highlight important cautions or potential issues.
-
-``` text
-{{< warning >}}
-Incorrect wiring may damage your device. Double-check connections before powering on.
-You can include **Markdown** formatting within the warning.
-{{< /warning >}}
-```
-
 ### `apiref`
 
 Creates a link to a C++ API header file.
@@ -307,6 +274,78 @@ Creates a page that automatically redirects to another URL.
 {{< redirect url="/some/path" >}}
 ```
 
+## Markdown features
+
+### `note`
+
+Creates a note blockquote/alert box to highlight important information.
+
+> [!NOTE]
+> This is important information that the reader should pay attention to.
+> You can include **Markdown** formatting within the block.
+
+```markdown
+> [!NOTE]
+> This is important information that the reader should pay attention to.
+> You can include **Markdown** formatting within the block.
+```
+
+### `important`
+
+Creates an important blockquote/alert box to highlight helpful information.
+
+> [!IMPORTANT]
+> This is helpful information that the reader should be aware of.
+> You can include **Markdown** formatting within the block.
+
+```markdown
+> [!IMPORTANT]
+> This is helpful information that the reader should be aware of.
+> You can include **Markdown** formatting within the block.
+```
+
+### `tip`
+
+Creates a tip blockquote/alert box to highlight helpful advice or best practices.
+
+> [!TIP]
+> For best results, place the sensor away from heat sources.
+> You can include **Markdown** formatting within the block.
+
+```markdown
+> [!TIP]
+> For best results, place the sensor away from heat sources.
+> You can include **Markdown** formatting within the block.
+```
+
+### `warning`
+
+Creates a warning blockquote/alert box to highlight important warnings or potential issues.
+
+> [!WARNING]
+> Incorrect wiring may damage your device. Double-check connections before powering on.
+> You can include **Markdown** formatting within the block.
+
+```markdown
+> [!WARNING]
+> Incorrect wiring may damage your device. Double-check connections before powering on.
+> You can include **Markdown** formatting within the block.
+```
+
+### `caution`
+
+Creates a caution blockquote/alert box to highlight important cautions or potential issues.
+
+> [!CAUTION]
+> Incorrect wiring may damage your device. Double-check connections before powering on.
+> You can include **Markdown** formatting within the block.
+
+```markdown
+> [!CAUTION]
+> Incorrect wiring may damage your device. Double-check connections before powering on.
+> You can include **Markdown** formatting within the block.
+```
+
 ## Conversion Scripts
 
 A Python script is included to help with the conversion process from RST:
diff --git a/content/changelog/2025.8.0.md b/content/changelog/2025.8.0.md
@@ -116,10 +116,9 @@ long-term security and maintainability.
 | Container Images (Docker) | **No action needed** - Already uses Python 3.12     |
 | Direct Installation (pip) | **Upgrade Python to 3.11+** before updating ESPHome |
 
-{{< warning >}}
-If you're running ESPHome directly on your machine with Python 3.10 or older, running `pip install -U esphome`
-will not upgrade beyond version 2025.7.x. You must upgrade your Python installation first.
-{{< /warning >}}
+> [!warning]
+> If you're running ESPHome directly on your machine with Python 3.10 or older, running `pip install -U esphome`
+> will not upgrade beyond version 2025.7.x. You must upgrade your Python installation first.
 
 ## Breaking Changes
 
diff --git a/themes/esphome-theme/assets/css/main.css b/themes/esphome-theme/assets/css/main.css
@@ -31,14 +31,15 @@
   --link-accent: #007070;
   --component-card-bg: #fff;
   --component-card-text: #333;
-  --admonition-note-bg: #e7f2fa;
-  --admonition-note-border: #3498db;
-  --admonition-note-title: #1080c0;
-  --admonition-tip-bg: #e8f8e5;
-  --admonition-tip-border: #2ecc71;
-  --admonition-tip-title: #2ecc71;
-  --admonition-warning-bg: #fff3cd;
-  --admonition-warning-border: #ffcc00;
+
+  --blockquote-bg: #f3f6f6;
+  --blockquote-border: var(--primary-color);
+
+  --alert-caution: #ff0000;
+  --alert-important: var(--text-color);
+  --alert-note: #5dade2;
+  --alert-tip: #7cb342;
+  --alert-warning: #ffcc32;
 }
 
 [data-theme="dark"] {
@@ -60,15 +61,11 @@
   --link-accent: #00a5a5;
   --component-card-bg: #23272e;
   --component-card-text: #f1f1f1;
-  --admonition-note-bg: #22313a;
-  --admonition-note-border: #5dade2;
-  --admonition-note-title: #5dade2;
-  --admonition-tip-bg: #1d2a1d;
-  --admonition-tip-border: #58d68d;
-  --admonition-tip-title: #58d68d;
-  --admonition-warning-bg: #23272e;
-  --admonition-warning-border: #ffcc00;
   --logo-text-color: #FFFFFF;
+
+  --blockquote-bg: #23272e;
+  --blockquote-border: var(--text-color);
+
 }
 
 
@@ -926,41 +923,56 @@ summary h4.shown {
   display: inline;
 }
 
-.admonition {
-  margin: 1.5em 0;
-  padding-top: 0.2em;
-  padding-left: 1em;
-  padding-right: 1em;
-  padding-bottom: 1em;
-  border-radius: 4px;
-  border-left: 4px solid;
+
+blockquote {
+  border-left: .25em solid var(--blockquote-border);
+  padding: 0.5em 1em;
+  margin: 1em 0;
+  background-color: var(--blockquote-bg);
 }
 
-.admonition.note {
-  background-color: var(--admonition-note-bg);
-  border-color: var(--admonition-note-border);
+blockquote.alert-caution {
+  border-left-color: var(--alert-caution);
 }
-.admonition.note .admonition-title {
-  color: var(--admonition-note-title);
+
+blockquote.alert-caution p.alert-heading {
+  color: var(--alert-caution);
 }
-.admonition.tip {
-  background-color: var(--admonition-tip-bg);
-  border-color: var(--admonition-tip-border);
+
+blockquote.alert-important {
+  border-left-color: var(--alert-important);
+}
+
+blockquote.alert-important p.alert-heading {
+  color: var(--alert-important);
 }
-.admonition.tip .admonition-title {
-  color: var(--admonition-tip-title);
+
+blockquote.alert-note {
+  border-left-color: var(--alert-note);
+}
+
+blockquote.alert-note p.alert-heading {
+  color: var(--alert-note);
 }
 
-.admonition.warning, .admonition.caution, .admonition.important {
-   background-color: var(--admonition-warning-bg);
-   border-color: #e67e22;
+blockquote.alert-tip {
+  border-left-color: var(--alert-tip);
 }
 
-.admonition.warning, .admonition.caution, .admonition.important .admonition-title {
-  color: #e67e22;
+blockquote.alert-tip p.alert-heading {
+  color: var(--alert-tip);
 }
 
-.admonition-title {
+blockquote.alert-warning {
+  border-left-color: var(--alert-warning);
+}
+
+blockquote.alert-warning p.alert-heading {
+  color: var(--alert-warning);
+}
+
+
+.alert p.alert-heading {
   font-weight: bold;
   margin: 0.5em 0;
 }
diff --git a/themes/esphome-theme/layouts/_default/_markup/render-blockquote-alert.html b/themes/esphome-theme/layouts/_default/_markup/render-blockquote-alert.html
@@ -0,0 +1,19 @@
+{{ $emojis := dict
+"caution" ":exclamation:"
+"important" ":information_source:"
+"note" ":information_source:"
+"tip" ":white_check_mark:"
+"warning" ":warning:"
+}}
+
+<blockquote class="alert alert-{{ .AlertType }}">
+  <p class="alert-heading">
+    {{ transform.Emojify (index $emojis .AlertType) }}
+    {{ with .AlertTitle }}
+    {{ . }}
+    {{ else }}
+    {{ or (i18n .AlertType) (title .AlertType) }}
+    {{ end }}
+  </p>
+  {{ .Text }}
+</blockquote>
diff --git a/themes/esphome-theme/layouts/_default/_markup/render-blockquote-regular.html b/themes/esphome-theme/layouts/_default/_markup/render-blockquote-regular.html
@@ -0,0 +1,3 @@
+<blockquote>
+  {{ .Text }}
+</blockquote>
diff --git a/themes/esphome-theme/layouts/_default/projects.html b/themes/esphome-theme/layouts/_default/projects.html
@@ -115,13 +115,13 @@ <h1>{{ .Title }}</h1>
   src="https://unpkg.com/esp-web-tools@10/dist/web/install-button.js?module"
 ></script>
 
-<div class="admonition note unsupported hidden">
-  <p class="admonition-title">Note</p>
+<blockquote class="alert alert-warning unsupported hidden">
+  <p class="alert-heading">⚠️ Warning</p>
   <p>
     This page requires a browser that supports WebSerial. Please open this
     website on your desktop using Google Chrome or Microsoft Edge.
   </p>
-</div>
+</blockquote>
 
 <div class="question-prompt">I want to create a:</div>
 <div class="types">
diff --git a/themes/esphome-theme/layouts/shortcodes/caution.html b/themes/esphome-theme/layouts/shortcodes/caution.html
@@ -1,6 +1,6 @@
 {{/*
   CAUTION SHORTCODE
-  Creates a caution admonition box to highlight important cautions or potential issues.
+  Creates a caution alert/callout box to highlight important cautions or potential issues.
   
   Usage: 
   {{< caution >}}
@@ -11,7 +11,7 @@
   Content:
   The content between the opening and closing shortcode tags will be displayed inside the caution box.
 */}}
-<div class="admonition caution">
-  <p class="admonition-title">Caution</p>
+<blockquote class="alert alert-caution">
+  <p class="alert-heading">{{ transform.Emojify ":exclamation:" }} Caution</p>
   {{ .Inner | .Page.RenderString}}
-</div>
+</blockquote>
diff --git a/themes/esphome-theme/layouts/shortcodes/important.html b/themes/esphome-theme/layouts/shortcodes/important.html
@@ -1,6 +1,6 @@
 {{/*
   Important SHORTCODE
-  Creates an "important" admonition box to highlight important cautions or potential issues.
+  Creates an "important" alert/callout box to highlight important cautions or potential issues.
   
   Usage: 
   {{< important >}}
@@ -11,7 +11,7 @@
   Content:
   The content between the opening and closing shortcode tags will be displayed inside the block.
 */}}
-<div class="admonition important">
-  <p class="admonition-title">Important</p>
-  {{ .Inner | .Page.RenderString}}
-</div>
+<blockquote class="alert alert-important">
+  <p class="alert-heading">{{ transform.Emojify ":information_source:" }} Important</p>
+  {{ .Inner | .Page.RenderString }}
+</blockquote>
diff --git a/themes/esphome-theme/layouts/shortcodes/note.html b/themes/esphome-theme/layouts/shortcodes/note.html
@@ -1,6 +1,6 @@
 {{/* 
   NOTE SHORTCODE
-  Creates a note admonition box to highlight important information.
+  Creates a note alert/callout box to highlight important information.
   
   Usage: 
   {{< note >}}
@@ -11,7 +11,7 @@
   Content:
   The content between the opening and closing shortcode tags will be displayed inside the note box.
 */}}
-<div class="admonition note">
-  <p class="admonition-title">Note</p>
+<blockquote class="alert alert-note">
+  <p class="alert-heading">{{ transform.Emojify ":information_source:" }} Note</p>
   {{ .Inner | .Page.RenderString }}
-</div>
+</blockquote>
diff --git a/themes/esphome-theme/layouts/shortcodes/tip.html b/themes/esphome-theme/layouts/shortcodes/tip.html
@@ -1,6 +1,6 @@
 {{/* 
   TIP SHORTCODE
-  Creates a tip admonition box to highlight helpful advice or best practices.
+  Creates a tip alert/callout box to highlight helpful advice or best practices.
   
   Usage: 
   {{< tip >}}
@@ -11,7 +11,7 @@
   Content:
   The content between the opening and closing shortcode tags will be displayed inside the tip box.
 */}}
-<div class="admonition tip">
-<p class="admonition-title">Tip</p>
+<blockquote class="alert alert-tip">
+<p class="alert-heading">{{ transform.Emojify ":white_check_mark:" }} Tip</p>
 {{- .Inner | .Page.RenderString -}}
-</div>
+</blockquote>
diff --git a/themes/esphome-theme/layouts/shortcodes/warning.html b/themes/esphome-theme/layouts/shortcodes/warning.html

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+<blockquote>`
	`2`	`+ {{ .Text }}`
	`3`	`+</blockquote>`