diff --git a/exampleSite/content/docs/shortcodes/index.md b/exampleSite/content/docs/shortcodes/index.md
index 1eb90e6a..b257b1b7 100644
--- a/exampleSite/content/docs/shortcodes/index.md
+++ b/exampleSite/content/docs/shortcodes/index.md
@@ -94,6 +94,9 @@ The alert sign (`+` or `-`) is optional to control whether the admonition is fol
 > **GitHub types:** `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`  
 > **Obsidian types:** `note`, `abstract`, `info`, `todo`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`
 
+> [!INFO]- Customize admonition
+> See the [admonition customization guide](https://github.com/nunocoracao/blowfish/blob/main/layouts/_default/_markup/render-blockquote.html).
+
 <br/><br/><br/>
 
 ## Article
diff --git a/exampleSite/content/docs/shortcodes/index.zh-cn.md b/exampleSite/content/docs/shortcodes/index.zh-cn.md
index fe13f5c0..ee3aa861 100644
--- a/exampleSite/content/docs/shortcodes/index.zh-cn.md
+++ b/exampleSite/content/docs/shortcodes/index.zh-cn.md
@@ -94,6 +94,9 @@ Admonition 的用途与 alert shortcode 类似，但其实现方式是通过 Hug
 > **GitHub 类型：** `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`  
 > **Obsidian 类型：** `note`, `abstract`, `info`, `todo`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`
 
+> [!INFO]- 自定义提示框
+> 请参阅 [提示框自定义指南](https://github.com/nunocoracao/blowfish/blob/main/layouts/_default/_markup/render-blockquote.html)。
+
 <br/><br/><br/>
 
 ## Article
diff --git a/layouts/_default/_markup/render-blockquote.html b/layouts/_default/_markup/render-blockquote.html
index 69de060e..6a8e5afa 100644
--- a/layouts/_default/_markup/render-blockquote.html
+++ b/layouts/_default/_markup/render-blockquote.html
@@ -1,36 +1,33 @@
-{{- if eq .Type "alert" -}}
-  {{- $typeMap := dict
-    "attention" "warning"
-    "check" "success"
-    "cite" "quote"
-    "done" "success"
-    "error" "danger"
-    "fail" "failure"
-    "faq" "question"
-    "hint" "tip"
-    "help" "question"
-    "missing" "failure"
-    "summary" "abstract"
-    "tldr" "abstract"
-  -}}
+{{- /* To customize your own admonitions, you can do the following:
 
-  {{- $iconMap := dict
-    "abstract" "file-lines"
-    "bug" "bug"
-    "caution" "fire"
-    "danger" "fire"
-    "example" "list-ol"
-    "failure" "xmark"
-    "important" "star"
-    "info" "circle-info"
-    "note" "circle-info"
-    "success" "check"
-    "todo" "list-check"
-    "tip" "lightbulb"
-    "question" "circle-question"
-    "quote" "quote-left"
-    "warning" "triangle-exclamation"
-  -}}
+  1. Change colors
+
+      Define your colors in `assets/css/custom.css` using the variables from:
+      https://github.com/nunocoracao/blowfish/blob/main/assets/css/components/admonition.css
+
+      Example:
+      ```
+      :root {
+          --adm-note-bg: red;
+      }
+      html.dark {
+          --adm-note-bg: green;
+      }
+      ```
+
+      This will update the background color for light and dark mode.
+
+  2. Change icons and type settings
+
+      You can override the default type and icon mappings by creating your own
+      `impls/hooks/admonition-maps.html` in your `layouts` folder.
+      This allows you to assign different icons or styles for each admonition type.
+*/ -}}
+
+{{- if eq .Type "alert" -}}
+  {{- $maps := partialCached "impls/hooks/admonition-maps.html" . -}}
+  {{- $typeMap := $maps.typeMap -}}
+  {{- $iconMap := $maps.iconMap -}}
 
   {{- $rawType := .AlertType | lower -}}
   {{- $normalizedType := index $typeMap $rawType | default $rawType -}}
diff --git a/layouts/partials/impls/hooks/admonition-maps.html b/layouts/partials/impls/hooks/admonition-maps.html
new file mode 100644
index 00000000..1bdd02f3
--- /dev/null
+++ b/layouts/partials/impls/hooks/admonition-maps.html
@@ -0,0 +1,34 @@
+{{- /* Override this file in your site to customize admonition type aliases and icon mappings */ -}}
+{{- return dict
+  "typeMap" (dict
+    "attention" "warning"
+    "check" "success"
+    "cite" "quote"
+    "done" "success"
+    "error" "danger"
+    "fail" "failure"
+    "faq" "question"
+    "hint" "tip"
+    "help" "question"
+    "missing" "failure"
+    "summary" "abstract"
+    "tldr" "abstract"
+  )
+  "iconMap" (dict
+    "abstract" "file-lines"
+    "bug" "bug"
+    "caution" "fire"
+    "danger" "fire"
+    "example" "list-ol"
+    "failure" "xmark"
+    "important" "star"
+    "info" "circle-info"
+    "note" "circle-info"
+    "success" "check"
+    "todo" "list-check"
+    "tip" "lightbulb"
+    "question" "circle-question"
+    "quote" "quote-left"
+    "warning" "triangle-exclamation"
+  )
+-}}