From 836a8a82d660c673b6705bdb5c7d79a262b65981 Mon Sep 17 00:00:00 2001
From: Alex Shpak <alex-shpak@users.noreply.github.com>
Date: Sun, 12 Oct 2025 13:27:05 +0200
Subject: [PATCH] Improve consistency of handling shrotcode attributes

---
 .../content.en/docs/shortcodes/tabs.md        |  2 +-
 layouts/_partials/docs/html-attrs.html        |  1 +
 layouts/_partials/docs/text/mapper.html       | 36 +++++++++++++++++++
 layouts/_shortcodes/asciinema.html            | 22 ++++++++----
 layouts/_shortcodes/badge.html                | 14 +++++---
 layouts/_shortcodes/button.html               | 14 +++++++-
 layouts/_shortcodes/columns.html              | 16 +++++++--
 layouts/_shortcodes/details.html              |  9 +++--
 layouts/_shortcodes/hint.html                 | 10 ++++--
 layouts/_shortcodes/image.html                | 11 +++---
 layouts/_shortcodes/katex.html                | 10 ++++--
 layouts/_shortcodes/mermaid.html              |  9 +++--
 layouts/_shortcodes/steps.html                |  9 +++--
 layouts/_shortcodes/tab.html                  |  2 +-
 layouts/_shortcodes/tabs.html                 |  9 +++--
 15 files changed, 140 insertions(+), 34 deletions(-)
 create mode 100644 layouts/_partials/docs/html-attrs.html
 create mode 100644 layouts/_partials/docs/text/mapper.html

diff --git a/exampleSite/content.en/docs/shortcodes/tabs.md b/exampleSite/content.en/docs/shortcodes/tabs.md
index f7c072e..e4bb21c 100644
--- a/exampleSite/content.en/docs/shortcodes/tabs.md
+++ b/exampleSite/content.en/docs/shortcodes/tabs.md
@@ -3,7 +3,7 @@
 Tabs let you organize content by context, for example installation instructions for each supported platform.
 
 ```tpl
-{{</* tabs "id" */>}}
+{{</* tabs */>}}
 {{%/* tab "MacOS" */%}} # MacOS Content {{%/* /tab */%}}
 {{%/* tab "Linux" */%}} # Linux Content {{%/* /tab */%}}
 {{%/* tab "Windows" */%}} # Windows Content {{%/* /tab */%}}
diff --git a/layouts/_partials/docs/html-attrs.html b/layouts/_partials/docs/html-attrs.html
new file mode 100644
index 0000000..46ec4e3
--- /dev/null
+++ b/layouts/_partials/docs/html-attrs.html
@@ -0,0 +1 @@
+{{- range $key, $value := . -}} {{- $key | htmlEscape -}}="{{- $value | safeHTMLAttr -}}" {{- end -}}
\ No newline at end of file
diff --git a/layouts/_partials/docs/text/mapper.html b/layouts/_partials/docs/text/mapper.html
new file mode 100644
index 0000000..6b56fec
--- /dev/null
+++ b/layouts/_partials/docs/text/mapper.html
@@ -0,0 +1,36 @@
+{{- /*
+  This is generic function the helps modifying and merging dictionaries, usually used for html attributes
+  Logic is executed in order defined below.
+  partial "docs/text/mapper" (dict
+    "attributes" (cond .IsNamedParams .Params dict)
+    "keep" (slice "id" "class" "tabindex" "alt" "title" "loading")
+    "set" (dict "href" "https://")
+    "merge" (dict "class" "a-class")
+    "delimiter" " " // Used when merging values
+    "delete" (slice "src")
+  )
+*/ -}}
+
+{{- $store := newScratch -}}
+{{- $allowlist := or (.keep) (slice "id" "class" "tabindex" "dir")}}
+{{- range $key, $value := .attributes -}}
+  {{- if in $allowlist $key -}}
+    {{- $store.Set $key $value -}}
+  {{- end -}}
+{{- end -}}
+
+{{- range $key, $value := .set -}}
+  {{- $store.Set $key (print $value) -}}
+{{- end -}}
+
+{{- range $key, $value := .merge -}}
+  {{- $merged := (slice) | append $value | append (or (index $.attributes $key) (slice)) -}}
+  {{- $delimiter := or ($.delimiter) (" ") }}
+  {{- $store.Set $key (delimit $merged $delimiter) -}}
+{{- end -}}
+
+{{- range $key := .delete -}}
+  {{- $store.Delete $key -}}
+{{- end -}}
+
+{{- return $store.Values -}}
diff --git a/layouts/_shortcodes/asciinema.html b/layouts/_shortcodes/asciinema.html
index de726f4..2c36e79 100644
--- a/layouts/_shortcodes/asciinema.html
+++ b/layouts/_shortcodes/asciinema.html
@@ -7,10 +7,18 @@
   <script defer src="{{ "asciinema/asciinema-auto.js" | relURL }}"></script>
   {{- .Page.Store.Set "asciinema" true -}}
 {{- end -}}
-
-{{- with (partial "docs/links/portable-image" (dict "Page" .Page "Destination" (index .Params "cast"))) -}}
-  {{- $opts := newScratch -}}
-  {{- $opts.Set "asciinema" $.Params -}}
-  {{- $opts.DeleteInMap "asciinema" "cast" -}}
-  <div class="asciinema book-asciinema" id="asciinema-{{ $.Ordinal }}" x-data-cast="{{ . | safeHTMLAttr }}" x-data-opts="{{ $opts.Get "asciinema" | jsonify | safeHTMLAttr }}"></div>
-{{- end -}}
+{{- $href := (partial "docs/links/portable-image" (dict "Page" .Page "Destination" (.Get "cast"))) -}}
+{{- .Store.Set "asciinema" .Params -}}
+{{- .Store.DeleteInMap "asciinema" "cast" -}}
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (dict)
+  "set" (dict
+    "id" (printf "asciinema-%d" .Ordinal)
+    "x-data-cast" $href
+    "x-data-opts" (.Store.Get "asciinema" | jsonify)
+  )
+  "merge" (dict
+    "class" (slice "asciinema" "book-asciinema")
+  )
+) -}}
+<div {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}></div>
diff --git a/layouts/_shortcodes/badge.html b/layouts/_shortcodes/badge.html
index 4079b24..ad6abeb 100644
--- a/layouts/_shortcodes/badge.html
+++ b/layouts/_shortcodes/badge.html
@@ -1,6 +1,12 @@
-{{- $style := default "default" (.Get "style") -}}
-<span class="book-badge {{ $style }}">
-  {{- with .Get "title" -}}<span class="book-badge-title">{{ . | plainify }}</span>{{- end -}}
-  {{- with .Get "value" -}}<span class="book-badge-value">{{ . | plainify }}</span>{{- end -}}
+{{- $style := or (.Get "style") (.Get 0) "default" -}}
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "merge" (dict
+    "class" (slice "book-badge" $style)
+  )
+) -}}
+<span {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>
+  {{- with or (.Get "title") (.Get 1) -}}<span class="book-badge-title">{{ . | plainify }}</span>{{- end -}}
+  {{- with or (.Get "value") (.Get 2) -}}<span class="book-badge-value">{{ . | plainify }}</span>{{- end -}}
 </span>
 {{- /* remove whitespaces */ -}}
diff --git a/layouts/_shortcodes/button.html b/layouts/_shortcodes/button.html
index d3c3a05..cdf251e 100644
--- a/layouts/_shortcodes/button.html
+++ b/layouts/_shortcodes/button.html
@@ -1,6 +1,18 @@
 {{- $href := partial "docs/links/portable-link" (dict "Page" .Page "Destination" (.Get "href")) -}}
 {{- $isRemote := (urls.Parse $href).IsAbs -}}
-<a {{ with $href }}href="{{ $href }}"{{ end }} {{ with $isRemote }}target="_blank" rel="noopener"{{ end }} class="book-btn{{ with .Get "class" }} {{ . }}{{ end }}">
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "set" (dict
+    "href" $href
+    "target" "_blank"
+    "rel" "noopener"
+  )
+  "merge" (dict
+    "class" "book-btn"
+  )
+  "delete" (cond $isRemote (slice) (slice "target" "rel"))
+) -}}
+<a {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>
   {{- .InnerDeindent -}}
 </a>
 {{- /* remove whitespaces */ -}}
diff --git a/layouts/_shortcodes/columns.html b/layouts/_shortcodes/columns.html
index dcffa6e..e80786b 100644
--- a/layouts/_shortcodes/columns.html
+++ b/layouts/_shortcodes/columns.html
@@ -1,7 +1,13 @@
 {{- $ratio := (split (.Get "ratio") ":") -}}
 {{- if strings.Contains .InnerDeindent "<--->" -}}
 {{- warnf "Columns shortcode seprator '<--->' is deprecated, use markdown list instead." -}}
-<div class="book-columns flex flex-wrap{{ with .Get "class" }} {{ . }}{{ end }}">
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "merge" (dict
+    "class" (slice "book-columns" "flex" "flex-wrap")
+  )
+) -}}
+<div {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>
 {{- range $index, $content := split .InnerDeindent "<--->" -}}
   {{- $grow := default 1 (index $ratio $index) -}}
   <div class="flex-even markdown-inner" style="flex-grow: {{ $grow }};">
@@ -15,7 +21,13 @@
     flex-grow: {{ default 1 $grow }};
   }
 {{- end -}}</style>{{- end -}}
-<div class="book-columns book-columns-{{ .Ordinal }}{{ with .Get "class" }} {{ . }}{{ end }}">
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "merge" (dict
+    "class" (slice "book-columns")
+  )
+) -}}
+<div {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>
 {{ .Inner | safeHTML -}}
 </div>
 {{- end -}}
diff --git a/layouts/_shortcodes/details.html b/layouts/_shortcodes/details.html
index 89409ec..299254b 100644
--- a/layouts/_shortcodes/details.html
+++ b/layouts/_shortcodes/details.html
@@ -1,5 +1,10 @@
-{{- /* remove whitespaces */ -}}
-<details {{ if or (.Get "open") (in .Params "open") }}open{{ end }}>
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "merge" (dict
+    "open" (cond .IsNamedParams (.Get "open") (in .Params "open"))
+  )
+) -}}
+<details {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>
 {{- $summary := cond .IsNamedParams (.Get "title") (.Get 0) -}}
 <summary>{{ $summary | .Page.RenderString }}</summary>
 {{- /* remove whitespaces */ -}}
diff --git a/layouts/_shortcodes/hint.html b/layouts/_shortcodes/hint.html
index 1e76688..8cec90b 100644
--- a/layouts/_shortcodes/hint.html
+++ b/layouts/_shortcodes/hint.html
@@ -1,5 +1,11 @@
-{{- /* remove whitespaces */ -}}
-<blockquote class="book-hint {{ default "default" (.Get 0) }}">
+{{- warnf "Hint shortcode is deprecated, use markdown alerts format: '> [!NOTE] ...'" -}}
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "merge" (dict
+    "class" (slice "book-hint" (or (.Get 0) "default"))
+  )
+) -}}
+<blockquote {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>
 {{ .Inner | safeHTML -}}
 </blockquote>
 {{- /* remove whitespaces */ -}}
diff --git a/layouts/_shortcodes/image.html b/layouts/_shortcodes/image.html
index 58f3d14..8a40f2d 100644
--- a/layouts/_shortcodes/image.html
+++ b/layouts/_shortcodes/image.html
@@ -1,11 +1,10 @@
 {{- $destination := partial "docs/links/portable-image" (dict "Page" .Page "Destination" (.Get "src")) -}}
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "keep" (slice "id" "class" "tabindex" "alt" "title" "loading")
+) -}}
 <label class="book-image" for="book-image-toggle-{{ .Ordinal }}">
   <input class="hidden toggle" type="checkbox" id="book-image-toggle-{{ .Ordinal }}" />
-  <img src="{{ $destination | safeURL }}"
-    {{- with .Get "alt"}} alt="{{ . }}"{{ end -}}
-    {{- with .Get "title"}} title="{{ . }}"{{ end -}}
-    {{- with .Get "loading"}} loading="{{ . }}"{{ end -}}
-    {{- with .Get "class"}} class="{{ . }}"{{ end -}}
-  />
+  <img src="{{ $destination | safeURL }}" {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }} />
 </label>
 {{- /* remove whitespaces */ -}}
\ No newline at end of file
diff --git a/layouts/_shortcodes/katex.html b/layouts/_shortcodes/katex.html
index 14fe0b1..d1fcb44 100644
--- a/layouts/_shortcodes/katex.html
+++ b/layouts/_shortcodes/katex.html
@@ -1,8 +1,14 @@
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "merge" (dict
+    "class" "book-katex"
+  )
+) -}}
 {{- if .Inner -}}
   {{- if .Get "display" -}}
-  <div>{{ printf "\\[ %s \\]" .Inner }}</div>
+  <div {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>{{ printf "\\[ %s \\]" .Inner }}</div>
   {{- else -}}
-  <span>{{ printf "\\( %s \\)" .Inner }}</span>
+  <span {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>{{ printf "\\( %s \\)" .Inner }}</span>
   {{- end -}}
 {{- end -}}
 {{- if not (.Page.Store.Get "katex") -}}
diff --git a/layouts/_shortcodes/mermaid.html b/layouts/_shortcodes/mermaid.html
index 859b6b0..e9d4d77 100644
--- a/layouts/_shortcodes/mermaid.html
+++ b/layouts/_shortcodes/mermaid.html
@@ -1,5 +1,10 @@
-{{- /* remove whitespaces */ -}}
-<pre class="mermaid{{ with .Get "class" }} {{ . }}{{ end }}">
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "merge" (dict
+    "class" "mermaid"
+  )
+) -}}
+<pre {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>
   {{- .Inner | htmlEscape | safeHTML -}}
 </pre>
 {{- if not (.Page.Store.Get "mermaid") -}}
diff --git a/layouts/_shortcodes/steps.html b/layouts/_shortcodes/steps.html
index 43ee928..0367d56 100644
--- a/layouts/_shortcodes/steps.html
+++ b/layouts/_shortcodes/steps.html
@@ -1,5 +1,10 @@
-{{- /* remove whitespaces */ -}}
-<div class="book-steps {{ with .Get "class" }}{{ . }}{{ end }}">
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "merge" (dict
+    "class" "book-steps"
+  )
+) -}}
+<div {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>
 {{ .Inner -}}
 </div>
 {{- /* remove whitespaces */ -}}
diff --git a/layouts/_shortcodes/tab.html b/layouts/_shortcodes/tab.html
index 5b4e4dc..f373d0f 100644
--- a/layouts/_shortcodes/tab.html
+++ b/layouts/_shortcodes/tab.html
@@ -1,4 +1,4 @@
-{{- $group := printf "tabs-%v" (default .Parent.Ordinal (.Parent.Get 0)) -}}
+{{- $group := printf "tabs-%v" .Parent.Ordinal -}}
 {{- $tab := printf "%s-%d" $group .Ordinal -}}
 <input type="radio" class="toggle" name="{{ $group }}" id="{{ $tab }}" {{ if not .Ordinal }}checked="checked"{{ end }} />
 {{- /* remove whitespaces */ -}}
diff --git a/layouts/_shortcodes/tabs.html b/layouts/_shortcodes/tabs.html
index f5507b7..907d01a 100644
--- a/layouts/_shortcodes/tabs.html
+++ b/layouts/_shortcodes/tabs.html
@@ -1,5 +1,10 @@
-{{- /* remove whitespaces */ -}}
-<div class="book-tabs">
+{{- $attributes := partial "docs/text/mapper" (dict
+  "attributes" (cond .IsNamedParams .Params dict)
+  "merge" (dict
+    "class" "book-tabs"
+  )
+) -}}
+<div {{ partial "docs/html-attrs" $attributes | safeHTMLAttr }}>
 {{- .Inner -}}
 </div>
 {{- /* remove whitespaces */ -}}