Merge pull request #2773 from alxhslm/carousel-captions

feat: Add captions argument to carousel shortcode

exampleSite/content/docs/shortcodes/index.md

@@ -252,10 +252,13 @@ Call to action
 | Parameter | Description |
 | --- | --- |
 | `images` | **Required.** A regex string to match image names or URLs. |
+| `captions` | **Optional.** A list of `key:caption` pairs. Keys can be image filenames (for local images) or full URLs (for remote images). Captions support Markdown. |
 | `aspectRatio` | **Optional.** The aspect ratio for the carousel. It is set to `16-9` by default. |
 | `interval` | **Optional.** The interval for the auto-scrooling, specified in milliseconds. Defaults to `2000` (2s) |
 <!-- prettier-ignore-end -->
 
+Captions are matched by key. For local images, use the filename (e.g. `01.jpg`). For remote images, use the full URL.
+
 **Example 1:** 16:9 aspect ratio and verbose list of images
 
 ```md
@@ -272,6 +275,14 @@ Call to action
 
 {{< carousel images="gallery/*" aspectRatio="21-9" interval="2500" >}}
 
+**Example 3:** Add captions
+
+```md
+{{</* carousel images="gallery/*" captions="{01.jpg:First image with *formatting*,02.jpg:Second image with a [link](https://example.com)}" */>}}
+```
+
+{{< carousel images="gallery/*" captions="{01.jpg:First image with *formatting*,02.jpg:Second image with a [link](https://example.com)}" >}}
+
 <br/><br/><br/>
 
 ## Chart

layouts/shortcodes/carousel.html

@@ -12,12 +12,28 @@
 {{ $images := slice }}
 {{ range $imagesTemp }}
   {{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
-    {{ $images = $images | append (resources.GetRemote .) }}
+    {{ $images = $images | append (dict "resource" (resources.GetRemote .) "key" .) }}
   {{ else }}
-    {{ $images = $images | append ($page.Match .) }}
+    {{ range ($page.Match .) }}
+      {{ $images = $images | append (dict "resource" . "key" .Name) }}
+    {{ end }}
   {{ end }}
 {{ end }}
 
+{{ $captionsParam := .Get "captions" }}
+{{ $captions := dict }}
+{{ if $captionsParam }}
+  {{ $captionsTemp := strings.TrimPrefix "{" $captionsParam }}
+  {{ $captionsTemp = strings.TrimSuffix "}" $captionsTemp }}
+  {{ range (strings.Split $captionsTemp ",") }}
+    {{ $pair := strings.Split . ":" }}
+    {{ if ge (len $pair) 2 }}
+      {{ $key := strings.TrimSpace (index $pair 0) }}
+      {{ $value := strings.TrimSpace (delimit (after 1 $pair) ":") }}
+      {{ $captions = merge $captions (dict $key $value) }}
+    {{ end }}
+  {{ end }}
+{{ end }}
 
 {{ if not .Parent }}<div class="width-patch"></div>{{ end }}
 <div
@@ -42,21 +58,44 @@
     {{ end }}
   </div>
 
-  <div class="relative w-full overflow-hidden after:clear-both after:block after:content-['']">
+  <div
+    class="relative w-full after:clear-both after:block after:content-['']"
+    style="overflow-x: clip; overflow-y: visible;">
     {{ range $index, $image := $images }}
-      {{ $hiddenClass := cond (eq $index 0) "" "hidden" }}
+    {{ $hiddenClass := cond (eq $index 0) "" "hidden" }}
-      <div
+    {{ $resource := index $image "resource" }}
-        class="relative float-left -mr-[100%] {{ $hiddenClass }} w-full transition-transform ease-in-out motion-reduce:transition-none"
+    {{ $key := index $image "key" }}
-        data-twe-carousel-item
+    {{ $caption := "" }}
-        style="transition-duration: {{ $interval }}ms;"
+    {{ $candidates := slice }}
-        {{ if eq $index 0 }}data-twe-carousel-active{{ end }}>
+    {{ if $resource }}
-        <div class="single_hero_background" style="aspect-ratio: {{ $aspectx }} / {{ $aspecty }};">
+    {{ $candidates = $candidates | append $resource.Name (path.Base $resource.Name) $resource.RelPermalink (path.Base $resource.RelPermalink) }}
+    {{ end }}
+    {{ if $key }}
+    {{ $candidates = $candidates | append $key (path.Base $key) }}
+    {{ end }}
+    {{ range $candidates }}
+    {{ if and (not $caption) . }}
+    {{ with (index $captions .) }}{{ $caption = . }}{{ end }}
+    {{ end }}
+    {{ end }}
+    <div
+      class="relative float-left -mr-[100%] {{ $hiddenClass }} w-full transition-transform ease-in-out motion-reduce:transition-none"
+      data-twe-carousel-item
+      style="transition-duration: {{ $interval }}ms;"
+      {{ if eq $index 0 }}data-twe-carousel-active{{ end }}>
+        <div class="single_hero_background relative overflow-hidden" style="aspect-ratio: {{ $aspectx }} / {{ $aspecty }};">
           <img
-            src="{{ $image.RelPermalink }}"
+            src="{{ $resource.RelPermalink }}"
             class="block absolute top-0 object-cover w-full h-full not-prose nozoom"
             alt="carousel image {{ add $index 1 }}">
         </div>
-      </div>
+        {{ if $caption }}
+        <figcaption
+          class="absolute left-0 right-0"
+          style="top: calc(100%);"
+        >{{ $caption | markdownify }}</figcaption>
+        {{ end }}
+    </div>
     {{ end }}
   </div>