From b4e44fda57ab07db9d1dcc071cc2c5e9bef6369c Mon Sep 17 00:00:00 2001
From: Jimmy <jimmy@cai.im>
Date: Tue, 17 Feb 2026 18:38:06 +0100
Subject: [PATCH] fix: enhance image caption handling by using title attribute
 if available (#1265)

* fix: enhance image caption handling by using title attribute if available

* feat: support markdown syntax inside image caption
---
 assets/ts/gallery.ts              | 17 +++++++++++++++--
 layouts/_markup/render-image.html |  5 +++++
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/assets/ts/gallery.ts b/assets/ts/gallery.ts
index 86f9345..9db9c3f 100644
--- a/assets/ts/gallery.ts
+++ b/assets/ts/gallery.ts
@@ -12,6 +12,15 @@ const wrap = (figures: HTMLElement[]) => {
     }
 }
 
+const unescapeHtml = (html: string) => {
+    /// Replace special HTML entities with their corresponding characters
+    return html.replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'");
+}
+
 export default (container: HTMLElement) => {
     /// The process of wrapping image with figure tag is done using JavaScript instead of only Hugo markdown render hook
     /// because it can not detect whether image is being wrapped by a link or not
@@ -64,9 +73,13 @@ export default (container: HTMLElement) => {
         figure.appendChild(el);
 
         /// Add figcaption if it exists
-        if (img.hasAttribute('alt')) {
+        let caption = img.getAttribute('alt');
+        if (img.getAttribute('data-title-escaped')) {
+            caption = unescapeHtml(img.getAttribute('data-title-escaped')!);
+        }
+        if (caption) {
             const figcaption = document.createElement('figcaption');
-            figcaption.innerText = img.getAttribute('alt')!;
+            figcaption.innerHTML = caption;
             figure.appendChild(figcaption);
         }
     }
diff --git a/layouts/_markup/render-image.html b/layouts/_markup/render-image.html
index a5316d9..f15d292 100644
--- a/layouts/_markup/render-image.html
+++ b/layouts/_markup/render-image.html
@@ -1,5 +1,6 @@
 {{- $image := partial "helper/image" (dict "Resources" .Page.Resources "Image" .Destination) -}}
 {{- $alt := .PlainText | safeHTML -}}
+{{- $title := .Title | markdownify -}}
 
 {{/* SVG and external images won't work with gallery layout, because their width and height attributes are unknown */}}
 {{- $galleryImage := and $image.Height $image.Width -}}
@@ -11,6 +12,10 @@
 	{{ with $alt }}
 		alt="{{ . }}"
 	{{ end }}
+    {{ with $title }}
+        title="{{ . }}"
+        data-title-escaped="{{ . | htmlEscape }}"
+    {{ end }}
 	{{ if $galleryImage }}
 		class="gallery-image" 
 		data-flex-grow="{{ div (mul $image.Width 100) $image.Height }}"