feat(shortcode): add shortcode for asciinema (#779)

* Add asciinema shortcode and usage examples

* Add asciinema shortcode

* Modify

* Modify

* Modify

* Modify

* Modify

* Remove old blog post and move content to dedicated documentation

* Add remote cast file support

* Fix remote cast file support

* Modify asciinema guide

* Add asciinema controls and idleTimeLimit

* fix the play button position issue and update some details

* Remove forced /casts/ prefix, implement flexible file lookup

layouts/_partials/scripts.html

@@ -8,3 +8,8 @@
 {{- if (.Store.Get "hasMermaid") -}}
   {{- partial "scripts/mermaid.html" . -}}
 {{- end -}}
+
+{{/* Asciinema */}}
+{{- if (.Store.Get "hasAsciinema") -}}
+  {{- partial "scripts/asciinema.html" . -}}
+{{- end -}}

layouts/_partials/scripts/asciinema.html

@@ -0,0 +1,114 @@
+{{- /* Asciinema */ -}}
+
+{{- $asciinemaBase := "" -}}
+{{- $useDefaultCdn := true -}}
+{{- with site.Params.asciinema.base -}}
+  {{- $asciinemaBase = . -}}
+  {{- $useDefaultCdn = false -}}
+{{- end -}}
+
+{{- $asciinemaJsAsset := "" -}}
+{{- with site.Params.asciinema.js -}}
+  {{- $asciinemaJsAsset = . -}}
+{{- end -}}
+
+{{- $asciinemaCssAsset := "" -}}
+{{- with site.Params.asciinema.css -}}
+  {{- $asciinemaCssAsset = . -}}
+{{- end -}}
+
+{{- /* If only js/css is set without base, use local asset loading */ -}}
+{{- if and $useDefaultCdn (or (ne $asciinemaJsAsset "") (ne $asciinemaCssAsset "")) -}}
+  {{- $useDefaultCdn = false -}}
+{{- end -}}
+
+{{- /* Set default CDN base if needed */ -}}
+{{- if $useDefaultCdn -}}
+  {{- $asciinemaBase = "https://cdn.jsdelivr.net/npm/asciinema-player@latest/dist/bundle" -}}
+{{- end -}}
+
+{{- $isRemoteBase := or (strings.HasPrefix $asciinemaBase "http://") (strings.HasPrefix $asciinemaBase "https://") -}}
+{{- $minSuffix := cond hugo.IsProduction ".min" "" -}}
+
+{{- /* CSS retrieval: get raw CSS from either local asset or remote, then process */ -}}
+{{- if $isRemoteBase -}}
+  {{- $cssPath := cond (ne $asciinemaCssAsset "") $asciinemaCssAsset "asciinema-player.css" -}}
+  {{- $asciinemaCssUrl := printf "%s/%s" $asciinemaBase $cssPath -}}
+  {{- with try (resources.GetRemote $asciinemaCssUrl) -}}
+    {{- with .Err -}}
+      {{- errorf "Could not retrieve Asciinema css file from %s. Reason: %s." $asciinemaCssUrl . -}}
+    {{- else with .Value -}}
+      {{- with resources.Copy "css/asciinema-player.css" . -}}
+        {{- $asciinemaCss := . | fingerprint -}}
+        <link rel="stylesheet" href="{{ $asciinemaCss.RelPermalink }}" integrity="{{ $asciinemaCss.Data.Integrity }}" crossorigin="anonymous" />
+      {{- end -}}
+    {{- end -}}
+  {{- end -}}
+{{- else if $asciinemaCssAsset -}}
+  {{- with resources.Get $asciinemaCssAsset -}}
+    {{- $asciinemaCss := . | fingerprint -}}
+    <link rel="stylesheet" href="{{ $asciinemaCss.RelPermalink }}" integrity="{{ $asciinemaCss.Data.Integrity }}" crossorigin="anonymous" />
+  {{- else -}}
+    {{- errorf "Asciinema css asset not found at %q" $asciinemaCssAsset -}}
+  {{- end -}}
+{{- end -}}
+
+{{- /* JS retrieval: get raw JS from either local asset or remote, then process */ -}}
+{{- if $isRemoteBase -}}
+  {{- $jsPath := cond (ne $asciinemaJsAsset "") $asciinemaJsAsset (printf "asciinema-player%s.js" $minSuffix) -}}
+  {{- $asciinemaJsUrl := printf "%s/%s" $asciinemaBase $jsPath -}}
+  {{- with try (resources.GetRemote $asciinemaJsUrl) -}}
+    {{- with .Err -}}
+      {{- errorf "Could not retrieve Asciinema js file from %s. Reason: %s." $asciinemaJsUrl . -}}
+    {{- else with .Value -}}
+      {{- with resources.Copy (printf "js/asciinema-player%s.js" $minSuffix) . -}}
+        {{- $asciinemaJs := . | fingerprint -}}
+        <script defer src="{{ $asciinemaJs.RelPermalink }}" integrity="{{ $asciinemaJs.Data.Integrity }}" crossorigin="anonymous"></script>
+      {{- end -}}
+    {{- end -}}
+  {{- end -}}
+{{- else if $asciinemaJsAsset -}}
+  {{- with resources.Get $asciinemaJsAsset -}}
+    {{- $asciinemaJs := . | fingerprint -}}
+    <script defer src="{{ $asciinemaJs.RelPermalink }}" integrity="{{ $asciinemaJs.Data.Integrity }}" crossorigin="anonymous"></script>
+  {{- else -}}
+    {{- errorf "Asciinema js asset not found at %q" $asciinemaJsAsset -}}
+  {{- end -}}
+{{- end -}}
+
+<script>
+  document.addEventListener("DOMContentLoaded", () => {
+    // Fix play button position issue
+    const style = document.createElement("style");
+    style.textContent = `
+      .ap-player .ap-overlay-start .ap-play-button span > svg {
+        display: inline;
+      }
+    `;
+    document.head.appendChild(style);
+    // Initialize asciinema players
+    document.querySelectorAll(".asciinema-player").forEach((el) => {
+      const castFile = el.dataset.castFile;
+      const theme = el.dataset.theme || "asciinema";
+      const speed = parseFloat(el.dataset.speed) || 1;
+      const autoplay = el.dataset.autoplay === "true";
+      const loop = el.dataset.loop === "true";
+      const poster = el.dataset.poster || "";
+      const markers = el.dataset.markers ? JSON.parse(el.dataset.markers) : [];
+
+      // Create asciinema player
+      if (window.AsciinemaPlayer) {
+        window.AsciinemaPlayer.create(castFile, el, {
+          theme: theme,
+          speed: speed,
+          autoplay: autoplay,
+          loop: loop,
+          poster: poster || undefined,
+          markers: markers.length > 0 ? markers : undefined,
+          controls: true,  // Always show user controls (bottom control bar)
+          idleTimeLimit: 2,  // Limit terminal inactivity to 2 seconds (compress pauses longer than 2s)
+        });
+      }
+    });
+  });
+</script>

layouts/_shortcodes/asciinema.html

@@ -0,0 +1,86 @@
+{{- /* Get parameters */ -}}
+{{- $castFile := .Get "file" | default (.Get 0) -}}
+{{- $theme := .Get "theme" | default "asciinema" -}}
+{{- $speed := .Get "speed" | default 1 -}}
+{{- $autoplay := .Get "autoplay" | default false -}}
+{{- $loop := .Get "loop" | default false -}}
+{{- $poster := .Get "poster" | default "" -}}
+{{- $markers := .Get "markers" | default "" -}}
+
+{{- /* Handle file path: support local files, absolute paths, and remote URLs */ -}}
+{{- $isLocal := not (urls.Parse $castFile).Scheme -}}
+{{- $isPage := and (eq .Page.Kind "page") (not .Page.BundleType) -}}
+
+{{- if $isLocal -}}
+  {{- /* Local file handling */ -}}
+  {{- $found := false -}}
+  
+  {{- /* Try page resources first */ -}}
+  {{- if not $isPage -}}
+    {{- with .Page.Resources.Get $castFile -}}
+      {{- $castFile = .RelPermalink -}}
+      {{- $found = true -}}
+    {{- end -}}
+  {{- end -}}
+  
+  {{- /* Try global resources if not found in page resources */ -}}
+  {{- if not $found -}}
+    {{- with resources.Get $castFile -}}
+      {{- $castFile = .RelPermalink -}}
+      {{- $found = true -}}
+    {{- end -}}
+  {{- end -}}
+  
+  {{- /* Try static files if not found in resources */ -}}
+  {{- if not $found -}}
+    {{- if hasPrefix $castFile "/" -}}
+      {{- $castFile = relURL (strings.TrimPrefix "/" $castFile) -}}
+      {{- $found = true -}}
+    {{- else -}}
+      {{- /* For relative paths, assume they're in static directory */ -}}
+      {{- $castFile = relURL $castFile -}}
+      {{- $found = true -}}
+    {{- end -}}
+  {{- end -}}
+  
+  {{- /* If still not found, raise an error */ -}}
+  {{- if not $found -}}
+    {{- errorf "Asciinema cast file not found: %s. Please ensure the file exists in your assets, static/, or provide a valid remote URL." $castFile -}}
+  {{- end -}}
+{{- end -}}
+
+{{- /* Build marker configuration */ -}}
+{{- $markerConfig := "" -}}
+{{- if $markers -}}
+  {{- $markerParts := slice -}}
+  {{- range (split $markers ",") -}}
+    {{- $item := trim . " " -}}
+    {{- $colonIndex := findRE ":" $item -}}
+    {{- if $colonIndex -}}
+      {{- /* Marker with label */ -}}
+      {{- $pair := split $item ":" -}}
+      {{- if ge (len $pair) 2 -}}
+        {{- $time := printf "%.1f" (float (trim (index $pair 0) " ")) -}}
+        {{- $label := trim (index $pair 1) " " -}}
+        {{- $markerParts = $markerParts | append (printf "[%s,\"%s\"]" $time $label) -}}
+      {{- end -}}
+    {{- else -}}
+      {{- /* Simple marker */ -}}
+      {{- $markerParts = $markerParts | append (printf "%.1f" (float $item)) -}}
+    {{- end -}}
+  {{- end -}}
+  {{- $markerConfig = printf "[%s]" (delimit $markerParts ",") -}}
+{{- end -}}
+
+{{- /* Mark page as using asciinema */ -}}
+{{- .Page.Store.Set "hasAsciinema" true -}}
+
+<div class="asciinema-player" 
+     data-cast-file="{{ $castFile }}"
+     data-theme="{{ $theme }}"
+     data-speed="{{ $speed }}"
+     data-autoplay="{{ $autoplay }}"
+     data-loop="{{ $loop }}"
+     {{- if ne $poster "" -}}data-poster="{{ $poster | safeURL }}"{{- end -}}
+     {{- if $markerConfig -}}data-markers="{{ $markerConfig | safeJS }}"{{- end -}}>
+</div>