From 87ad65622c8b32c9fc1e94e4f86c1ab6e99f700a Mon Sep 17 00:00:00 2001
From: Joan Puigcerver <joapuiib@gmail.com>
Date: Tue, 31 Mar 2026 11:16:32 +0200
Subject: [PATCH 1/4] admonition refactor

---
 docs/reference/admonitions.md                 | 44 +++----------
 .../main/extensions/markdown/_admonition.scss | 65 +++++++------------
 2 files changed, 35 insertions(+), 74 deletions(-)

diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index c4defa031f..d0e446597f 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -166,7 +166,7 @@ can use your existing admonitions and indent the desired ones:
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
-    
+
     !!! note "Inner Note"
 
         Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
@@ -181,7 +181,7 @@ can use your existing admonitions and indent the desired ones:
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
-    
+
     !!! note "Inner Note"
 
         Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
@@ -467,44 +467,20 @@ If you want to add a custom admonition type, all you need is a color and an
 and add the following CSS to an [additional style sheet]:
 
 <style>
-  :root {
-    --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
-  }
-  .md-typeset .admonition.pied-piper,
-  .md-typeset details.pied-piper {
-    border-color: rgb(43, 155, 70);
-  }
-  .md-typeset .pied-piper > .admonition-title,
-  .md-typeset .pied-piper > summary {
-    background-color: rgba(43, 155, 70, 0.1);
-  }
-  .md-typeset .pied-piper > .admonition-title::before,
-  .md-typeset .pied-piper > summary::before {
-    background-color: rgb(43, 155, 70);
-    -webkit-mask-image: var(--md-admonition-icon--pied-piper);
-            mask-image: var(--md-admonition-icon--pied-piper);
+  .md-typeset .admonition.pied-piper {
+    --md-admonition-icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>');
+    --md-admonition-color: rgb(43, 155, 70);
+    --md-admonition-title-bg-color: #2b9b464b;
   }
 </style>
 
 === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
 
     ``` css
-    :root {
-      --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
-    }
-    .md-typeset .admonition.pied-piper,
-    .md-typeset details.pied-piper {
-      border-color: rgb(43, 155, 70);
-    }
-    .md-typeset .pied-piper > .admonition-title,
-    .md-typeset .pied-piper > summary {
-      background-color: rgba(43, 155, 70, 0.1);
-    }
-    .md-typeset .pied-piper > .admonition-title::before,
-    .md-typeset .pied-piper > summary::before {
-      background-color: rgb(43, 155, 70);
-      -webkit-mask-image: var(--md-admonition-icon--pied-piper);
-              mask-image: var(--md-admonition-icon--pied-piper);
+    .md-typeset .admonition.pied-piper {
+      --md-admonition-icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>');
+      --md-admonition-color: rgb(43, 155, 70);
+      --md-admonition-title-bg-color: #2b9b464b;
     }
     ```
 
diff --git a/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss b/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss
index b558704bae..4951ec1bbc 100644
--- a/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss
+++ b/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss
@@ -43,18 +43,34 @@ $admonitions: (
   "quote":    format-quote-close    $clr-grey
 ) !default;
 
+
 // ----------------------------------------------------------------------------
-// Rules: layout
+// Rules: flavours
 // ----------------------------------------------------------------------------
 
 // Admonition variables
 :root {
   @each $name, $props in $admonitions {
+    --md-admonition-color--#{$name}:
+      #{list.nth($props, 2)};
+    --md-admonition-title-bg-color--#{$name}:
+      #{color.adjust(list.nth($props, 2), $alpha: -0.7)};
     --md-admonition-icon--#{$name}:
       svg-load("material/#{list.nth($props, 1)}.svg");
   }
 }
 
+// Admonition flavour - sets color and icon variables for each type
+@each $name, $props in $admonitions {
+  .md-typeset .admonition.#{$name} {
+    --md-admonition-color: var(--md-admonition-color--#{$name});
+    --md-admonition-title-bg-color: var(--md-admonition-title-bg-color--#{$name});
+    --md-admonition-icon: var(--md-admonition-icon--#{$name});
+  }
+}
+
+// ----------------------------------------------------------------------------
+// Rules: layout
 // ----------------------------------------------------------------------------
 
 // Scoped in typesetted content to match specificity of regular content
@@ -63,13 +79,17 @@ $admonitions: (
   // Admonition - note that all styles also apply to details tags, which are
   // rendered as collapsible admonitions with summary elements as titles.
   .admonition {
+    --md-admonition-color: #{$clr-blue-a200};
+    --md-admonition-title-bg-color: #{color.adjust($clr-blue-a200, $alpha: -0.7)};
+    --md-admonition-icon: var(--md-admonition-icon--note);
+
     display: flow-root;
     padding: 0 px2rem(12px);
     margin: px2em(20px, 12.8px) 0;
     font-size: px2rem(12.8px);
     color: var(--md-admonition-fg-color);
     background-color: var(--md-admonition-bg-color);
-    border: px2rem(1px) solid $clr-blue-a200;
+    border: px2rem(1px) solid var(--md-admonition-title-bg-color);
     border-radius: px2rem(8px);
     // box-shadow: var(--md-shadow-z1);
     // transition: box-shadow 125ms;
@@ -126,7 +146,7 @@ $admonitions: (
     margin-block: 0;
     margin-inline: px2rem(-12px);
     font-weight: 700;
-    background-color: color.adjust($clr-blue-a200, $alpha: -0.9);
+    background-color: var(--md-admonition-title-bg-color);
     border: none;
     border-inline-start-width: px2rem(4px);
     border-start-start-radius: px2rem(8px);
@@ -147,8 +167,8 @@ $admonitions: (
       width: px2rem(20px);
       height: px2rem(20px);
       content: "";
-      background-color: $clr-blue-a200;
-      mask-image: var(--md-admonition-icon--note);
+      background-color: var(--md-admonition-color);
+      mask-image: var(--md-admonition-icon);
       mask-repeat: no-repeat;
       mask-position: center;
       mask-size: contain;
@@ -160,38 +180,3 @@ $admonitions: (
     }
   }
 }
-
-// ----------------------------------------------------------------------------
-// Rules: flavours
-// ----------------------------------------------------------------------------
-
-// Define admonition flavors
-@each $name, $props in $admonitions {
-  $tint: list.nth($props, 2);
-
-  // Admonition flavour
-  .md-typeset .admonition.#{$name} {
-    border-color: color.adjust($tint, $alpha: -0.7);
-
-    // // Admonition on focus
-    // &:focus-within {
-    //   box-shadow: 0 0 0 px2rem(4px) color.adjust($tint, $alpha: -0.9);
-    // }
-  }
-
-  // Admonition flavour title
-  .md-typeset .#{$name} > .admonition-title {
-    background-color: color.adjust($tint, $alpha: -0.7);
-
-    // Admonition icon
-    &::before {
-      background-color: $tint;
-      mask-image: var(--md-admonition-icon--#{$name});
-    }
-
-    // Details marker
-    &::after {
-      color: $tint;
-    }
-  }
-}

From fdd64b7c7a77c693ba4b737c6bb23d62a509baf9 Mon Sep 17 00:00:00 2001
From: Joan Puigcerver <joapuiib@gmail.com>
Date: Thu, 2 Apr 2026 19:08:24 +0200
Subject: [PATCH 2/4] admonition refactor and classical appareance

---
 docs/reference/admonitions.md                 | 44 +++++++++++++++++--
 .../main/extensions/markdown/_admonition.scss | 14 +++---
 2 files changed, 45 insertions(+), 13 deletions(-)

diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index d0e446597f..e06c3a4660 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -420,12 +420,13 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
+
 ## Customization
 
 ### Classic admonitions
+In previous versions, admonitions had a slightly different appearance.
 
-Prior to version <!-- md:version 8.5.6 -->, admonitions had a slightly
-different appearance:
+#### Prior to version <!-- md:version 8.5.6 -->
 
 !!! classic "Note"
 
@@ -438,6 +439,8 @@ If you want to restore this appearance, add the following CSS to an
 
 <style>
   .md-typeset .admonition.classic {
+    --md-admonition-title-bg-color: color-mix(in srgb, var(--md-admonition-color), transparent 90%);
+    --md-admonition-border-color: var(--md-admonition-color);
     border-width: 0;
     border-left-width: 4px;
   }
@@ -448,6 +451,8 @@ If you want to restore this appearance, add the following CSS to an
     ``` css
     .md-typeset .admonition,
     .md-typeset details {
+      --md-admonition-title-bg-color: color-mix(in srgb, var(--md-admonition-color), transparent 90%);
+      --md-admonition-border-color: var(--md-admonition-color);
       border-width: 0;
       border-left-width: 4px;
     }
@@ -460,6 +465,39 @@ If you want to restore this appearance, add the following CSS to an
       - stylesheets/extra.css
     ```
 
+#### Prior to version <!-- md:version 10.0.6 -->
+!!! classic2 "Note"
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+If you want to restore this appearance, add the following CSS to an
+[additional style sheet]:
+
+<style>
+  .md-typeset .admonition.classic2 {
+    --md-admonition-title-bg-color: color-mix(in srgb, var(--md-admonition-color), transparent 90%);
+    --md-admonition-border-color: var(--md-admonition-color);
+  }
+</style>
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+    ``` css
+    .md-typeset .admonition,
+    .md-typeset details {
+      --md-admonition-title-bg-color: color-mix(in srgb, var(--md-admonition-color), transparent 90%);
+      --md-admonition-border-color: var(--md-admonition-color);
+    }
+    ```
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+    ``` yaml
+    extra_css:
+      - stylesheets/extra.css
+    ```
+
 ### Custom admonitions
 
 If you want to add a custom admonition type, all you need is a color and an
@@ -470,7 +508,6 @@ and add the following CSS to an [additional style sheet]:
   .md-typeset .admonition.pied-piper {
     --md-admonition-icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>');
     --md-admonition-color: rgb(43, 155, 70);
-    --md-admonition-title-bg-color: #2b9b464b;
   }
 </style>
 
@@ -480,7 +517,6 @@ and add the following CSS to an [additional style sheet]:
     .md-typeset .admonition.pied-piper {
       --md-admonition-icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>');
       --md-admonition-color: rgb(43, 155, 70);
-      --md-admonition-title-bg-color: #2b9b464b;
     }
     ```
 
diff --git a/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss b/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss
index 1b2c9e78f6..0b50f4fabd 100644
--- a/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss
+++ b/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss
@@ -51,12 +51,8 @@ $admonitions: (
 // Admonition variables
 :root {
   @each $name, $props in $admonitions {
-    --md-admonition-color--#{$name}:
-      #{list.nth($props, 2)};
-    --md-admonition-title-bg-color--#{$name}:
-      #{color.adjust(list.nth($props, 2), $alpha: -0.7)};
-    --md-admonition-icon--#{$name}:
-      svg-load("material/#{list.nth($props, 1)}.svg");
+    --md-admonition-color--#{$name}: #{list.nth($props, 2)};
+    --md-admonition-icon--#{$name}: svg-load("material/#{list.nth($props, 1)}.svg");
   }
 }
 
@@ -64,7 +60,6 @@ $admonitions: (
 @each $name, $props in $admonitions {
   .md-typeset .admonition.#{$name} {
     --md-admonition-color: var(--md-admonition-color--#{$name});
-    --md-admonition-title-bg-color: var(--md-admonition-title-bg-color--#{$name});
     --md-admonition-icon: var(--md-admonition-icon--#{$name});
   }
 }
@@ -80,8 +75,9 @@ $admonitions: (
   // rendered as collapsible admonitions with summary elements as titles.
   .admonition {
     --md-admonition-color: #{$clr-blue-a200};
-    --md-admonition-title-bg-color: #{color.adjust($clr-blue-a200, $alpha: -0.7)};
+    --md-admonition-title-bg-color: color-mix(in srgb, var(--md-admonition-color), transparent 70%);
     --md-admonition-icon: var(--md-admonition-icon--note);
+    --md-admonition-border-color: var(--md-admonition-title-bg-color);
 
     display: flow-root;
     padding: 0 px2rem(12px);
@@ -89,7 +85,7 @@ $admonitions: (
     font-size: px2rem(12.8px);
     color: var(--md-admonition-fg-color);
     background-color: var(--md-admonition-bg-color);
-    border: px2rem(1px) solid var(--md-admonition-title-bg-color);
+    border: px2rem(1px) solid var(--md-admonition-border-color);
     border-radius: px2rem(8px);
     overflow: hidden;
     // box-shadow: var(--md-shadow-z1);

From 14a11037763e4f11986cd5725d88b62e3e97a4f3 Mon Sep 17 00:00:00 2001
From: Joan Puigcerver <joapuiib@gmail.com>
Date: Thu, 2 Apr 2026 19:11:04 +0200
Subject: [PATCH 3/4] use note variable as defaul color

---
 .../stylesheets/main/extensions/markdown/_admonition.scss       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss b/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss
index 0b50f4fabd..143fcd811d 100644
--- a/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss
+++ b/src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss
@@ -74,7 +74,7 @@ $admonitions: (
   // Admonition - note that all styles also apply to details tags, which are
   // rendered as collapsible admonitions with summary elements as titles.
   .admonition {
-    --md-admonition-color: #{$clr-blue-a200};
+    --md-admonition-color: var(--md-admonition-color--note);
     --md-admonition-title-bg-color: color-mix(in srgb, var(--md-admonition-color), transparent 70%);
     --md-admonition-icon: var(--md-admonition-icon--note);
     --md-admonition-border-color: var(--md-admonition-title-bg-color);

From 29283523c34c9df3840770d409fa1918ac582f22 Mon Sep 17 00:00:00 2001
From: Joan Puigcerver <joapuiib@gmail.com>
Date: Thu, 2 Apr 2026 20:11:18 +0200
Subject: [PATCH 4/4] docs: change custom admonition color to hex

---
 docs/reference/admonitions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index e06c3a4660..9039770cae 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -507,7 +507,7 @@ and add the following CSS to an [additional style sheet]:
 <style>
   .md-typeset .admonition.pied-piper {
     --md-admonition-icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>');
-    --md-admonition-color: rgb(43, 155, 70);
+    --md-admonition-color: #2b9b46;
   }
 </style>
 
@@ -516,7 +516,7 @@ and add the following CSS to an [additional style sheet]:
     ``` css
     .md-typeset .admonition.pied-piper {
       --md-admonition-icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>');
-      --md-admonition-color: rgb(43, 155, 70);
+      --md-admonition-color: #2b9b46;
     }
     ```