From 0f7f27b916ba72922612d452afd13a569982e54c Mon Sep 17 00:00:00 2001
From: ZhenShuo Leo <98386542+ZhenShuo2021@users.noreply.github.com>
Date: Sun, 31 Aug 2025 17:16:10 +0800
Subject: [PATCH] refactor(article-link): separate Go templates from HTML
 rendering

Add descriptions for the purpose of each template.
It takes time to figure out their use every time.
---
 layouts/partials/article-link/_shortcode.html | 42 +++++++++--------
 .../partials/article-link/card-related.html   | 42 ++++++++++-------
 layouts/partials/article-link/card.html       | 46 +++++++++++--------
 layouts/partials/article-link/simple.html     | 44 ++++++++++--------
 4 files changed, 103 insertions(+), 71 deletions(-)

diff --git a/layouts/partials/article-link/_shortcode.html b/layouts/partials/article-link/_shortcode.html
index 3d13844b..62a7336e 100644
--- a/layouts/partials/article-link/_shortcode.html
+++ b/layouts/partials/article-link/_shortcode.html
@@ -1,3 +1,6 @@
+{{/* Used by
+  1. article shortcode
+*/}}
 {{ $target := .target }}
 {{ $shortcodeShowSummary := .showSummary }}
 {{ $shortcodeCompactSummary := .compactSummary }}
@@ -29,30 +32,33 @@
   {{ $articleClasses = delimit (slice $articleClasses "max-w-prose") " " }}
 {{ end }}
 
+{{ $images := $target.Resources.ByType "image" }}
+{{ $featured := $images.GetMatch "*feature*" }}
+{{ $featuredURL := "" }}
+{{ if not $featured }}{{ $featured = $images.GetMatch "{*cover*,*thumbnail*}" }}{{ end }}
+{{ if and $target.Params.featureimage (not $featured) }}
+  {{ $url:= $target.Params.featureimage }}
+  {{ $featured = resources.GetRemote $url }}
+{{ end }}
+{{ if not $featured }}
+  {{ with site.Params.defaultFeaturedImage }}{{ $featured = resources.Get . }}{{ end }}
+{{ end }}
+{{ if $target.Params.hideFeatureImage }}{{ $featured = false }}{{ end }}
+{{ with $featured }}
+  {{ $featuredURL = .RelPermalink }}
+  {{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
+    {{ $featuredURL = (.Resize "600x").RelPermalink }}
+  {{ end }}
+{{ end }}
+
 
 <div class="{{ $articleClasses }}">
   <a
     {{ partial "article-link/_external-link.html" $target | safeHTMLAttr }}
     class="absolute inset-0"
     aria-label="{{ $.Title }}"></a>
-
-  {{ $images := $target.Resources.ByType "image" }}
-  {{ $featured := $images.GetMatch "*feature*" }}
-  {{ if not $featured }}{{ $featured = $images.GetMatch "{*cover*,*thumbnail*}" }}{{ end }}
-  {{ if and $target.Params.featureimage (not $featured) }}
-    {{ $url:= $target.Params.featureimage }}
-    {{ $featured = resources.GetRemote $url }}
-  {{ end }}
-  {{ if not $featured }}
-    {{ with site.Params.defaultFeaturedImage }}{{ $featured = resources.Get . }}{{ end }}
-  {{ end }}
-  {{ if $target.Params.hideFeatureImage }}{{ $featured = false }}{{ end }}
-  {{ with $featured }}
-    {{ $featuredURL := .RelPermalink }}
-    {{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
-      {{ $featuredURL = (.Resize "600x").RelPermalink }}
-    {{ end }}
-    <div class="{{ $articleImageClasses }}" style="background-image:url({{ $featuredURL }});"></div>
+  {{ with $featuredURL }}
+    <div class="{{ $articleImageClasses }}" style="background-image:url({{ . }});"></div>
   {{ end }}
   <div class="{{ $articleInnerClasses }}">
     <div class="items-center text-start text-xl font-semibold">
diff --git a/layouts/partials/article-link/card-related.html b/layouts/partials/article-link/card-related.html
index 9e5254b4..b5f65382 100644
--- a/layouts/partials/article-link/card-related.html
+++ b/layouts/partials/article-link/card-related.html
@@ -1,27 +1,35 @@
+{{/* Used by
+  1. layouts/partials/related.html (related articles in single page)
+*/}}
 {{ $disableImageOptimization := .Page.Site.Params.disableImageOptimization | default false }}
+
+{{ $images := $.Resources.ByType "image" }}
+{{ $featured := $images.GetMatch "*feature*" }}
+{{ $featuredURL := "" }}
+{{ if not $featured }}{{ $featured = $images.GetMatch "{*cover*,*thumbnail*}" }}{{ end }}
+{{ if and .Params.featureimage (not $featured) }}
+  {{ $url:= .Params.featureimage }}
+  {{ $featured = resources.GetRemote $url }}
+{{ end }}
+{{ if not $featured }}
+  {{ with .Site.Params.defaultFeaturedImage }}{{ $featured = resources.Get . }}{{ end }}
+{{ end }}
+{{ with $featured }}
+  {{ $featuredURL = .RelPermalink }}
+  {{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
+    {{ $featuredURL = (.Resize "600x").RelPermalink }}
+  {{ end }}
+{{ end }}
+
+
 <div
   class="group-hover-card group relative min-h-full min-w-full overflow-hidden rounded border border-2 border-neutral-200 shadow-2xl dark:border-neutral-700">
   <a
     {{ partial "article-link/_external-link.html" . | safeHTMLAttr }}
     class="absolute inset-0"
     aria-label="{{ $.Title }}"></a>
-
-  {{ $images := $.Resources.ByType "image" }}
-  {{ $featured := $images.GetMatch "*feature*" }}
-  {{ if not $featured }}{{ $featured = $images.GetMatch "{*cover*,*thumbnail*}" }}{{ end }}
-  {{ if and .Params.featureimage (not $featured) }}
-    {{ $url:= .Params.featureimage }}
-    {{ $featured = resources.GetRemote $url }}
-  {{ end }}
-  {{ if not $featured }}
-    {{ with .Site.Params.defaultFeaturedImage }}{{ $featured = resources.Get . }}{{ end }}
-  {{ end }}
-  {{ with $featured }}
-    {{ $featuredURL := .RelPermalink }}
-    {{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
-      {{ $featuredURL = (.Resize "600x").RelPermalink }}
-    {{ end }}
-    <div class="thumbnail_card_related nozoom w-full" style="background-image:url({{ $featuredURL }});"></div>
+  {{ with $featuredURL }}
+    <div class="thumbnail_card_related nozoom w-full" style="background-image:url({{ . }});"></div>
   {{ end }}
   {{ if and .Draft .Site.Params.article.showDraftLabel }}
     <span class="absolute top-0 right-0 m-2">
diff --git a/layouts/partials/article-link/card.html b/layouts/partials/article-link/card.html
index df347f35..6d0bc58d 100644
--- a/layouts/partials/article-link/card.html
+++ b/layouts/partials/article-link/card.html
@@ -1,28 +1,38 @@
+{{/* Used by
+  1. list.html and term.html (when the cardView option is enabled)
+  2. Recent articles template (when the cardView option is enabled)
+  3. Shortcode list.html
+*/}}
 {{ $disableImageOptimization := .Page.Site.Params.disableImageOptimization | default false }}
+
+{{ $images := $.Resources.ByType "image" }}
+{{ $featured := $images.GetMatch "*feature*" }}
+{{ $featuredURL := "" }}
+{{ if not $featured }}{{ $featured = $images.GetMatch "{*cover*,*thumbnail*}" }}{{ end }}
+{{ if and .Params.featureimage (not $featured) }}
+  {{ $url:= .Params.featureimage }}
+  {{ $featured = resources.GetRemote $url }}
+{{ end }}
+{{ if not $featured }}
+  {{ with .Site.Params.defaultFeaturedImage }}{{ $featured = resources.Get . }}{{ end }}
+{{ end }}
+{{ if .Params.hideFeatureImage }}{{ $featured = false }}{{ end }}
+{{ with $featured }}
+  {{ $featuredURL = .RelPermalink }}
+  {{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
+    {{ $featuredURL = (.Resize "600x").RelPermalink }}
+  {{ end }}
+{{ end }}
+
+
 <div
   class="group-hover-card group relative min-h-full min-w-full overflow-hidden rounded border border-2 border-neutral-200 shadow-2xl dark:border-neutral-700">
   <a
     {{ partial "article-link/_external-link.html" . | safeHTMLAttr }}
     class="absolute inset-0"
     aria-label="{{ $.Title }}"></a>
-
-  {{ $images := $.Resources.ByType "image" }}
-  {{ $featured := $images.GetMatch "*feature*" }}
-  {{ if not $featured }}{{ $featured = $images.GetMatch "{*cover*,*thumbnail*}" }}{{ end }}
-  {{ if and .Params.featureimage (not $featured) }}
-    {{ $url:= .Params.featureimage }}
-    {{ $featured = resources.GetRemote $url }}
-  {{ end }}
-  {{ if not $featured }}
-    {{ with .Site.Params.defaultFeaturedImage }}{{ $featured = resources.Get . }}{{ end }}
-  {{ end }}
-  {{ if .Params.hideFeatureImage }}{{ $featured = false }}{{ end }}
-  {{ with $featured }}
-    {{ $featuredURL := .RelPermalink }}
-    {{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
-      {{ $featuredURL = (.Resize "600x").RelPermalink }}
-    {{ end }}
-    <div class="thumbnail_card nozoom w-full" style="background-image:url({{ $featuredURL }});"></div>
+  {{ with $featuredURL }}
+    <div class="thumbnail_card nozoom w-full" style="background-image:url({{ . }});"></div>
   {{ end }}
   {{ if and .Draft .Site.Params.article.showDraftLabel }}
     <span class="absolute top-0 right-0 m-2">
diff --git a/layouts/partials/article-link/simple.html b/layouts/partials/article-link/simple.html
index 7d819dc0..e098fa4b 100644
--- a/layouts/partials/article-link/simple.html
+++ b/layouts/partials/article-link/simple.html
@@ -1,3 +1,8 @@
+{{/* Used by
+  1. list.html and term.html (when the cardView option is not enabled)
+  2. Recent articles template (when the cardView option is not enabled)
+  3. Shortcode list.html
+*/}}
 {{ $constrainItemsWidth := .Page.Site.Params.list.constrainItemsWidth | default false }}
 
 {{ $articleClasses := "group-hover-card group flex flex-wrap md:flex-nowrap article relative" }}
@@ -27,30 +32,33 @@
   {{ $articleClasses = delimit (slice $articleClasses "max-w-prose") " " }}
 {{ end }}
 
+{{ $images := $.Resources.ByType "image" }}
+{{ $featured := $images.GetMatch "*feature*" }}
+{{ $featuredURL := "" }}
+{{ if not $featured }}{{ $featured = $images.GetMatch "{*cover*,*thumbnail*}" }}{{ end }}
+{{ if and .Params.featureimage (not $featured) }}
+  {{ $url:= .Params.featureimage }}
+  {{ $featured = resources.GetRemote $url }}
+{{ end }}
+{{ if not $featured }}
+  {{ with .Site.Params.defaultFeaturedImage }}{{ $featured = resources.Get . }}{{ end }}
+{{ end }}
+{{ if .Params.hideFeatureImage }}{{ $featured = false }}{{ end }}
+{{ with $featured }}
+  {{ $featuredURL = .RelPermalink }}
+  {{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
+    {{ $featuredURL = (.Resize "600x").RelPermalink }}
+  {{ end }}
+{{ end }}
+
 
 <div class="{{ $articleClasses }}">
   <a
     {{ partial "article-link/_external-link.html" . | safeHTMLAttr }}
     class="absolute inset-0"
     aria-label="{{ $.Title }}"></a>
-
-  {{ $images := $.Resources.ByType "image" }}
-  {{ $featured := $images.GetMatch "*feature*" }}
-  {{ if not $featured }}{{ $featured = $images.GetMatch "{*cover*,*thumbnail*}" }}{{ end }}
-  {{ if and .Params.featureimage (not $featured) }}
-    {{ $url:= .Params.featureimage }}
-    {{ $featured = resources.GetRemote $url }}
-  {{ end }}
-  {{ if not $featured }}
-    {{ with .Site.Params.defaultFeaturedImage }}{{ $featured = resources.Get . }}{{ end }}
-  {{ end }}
-  {{ if .Params.hideFeatureImage }}{{ $featured = false }}{{ end }}
-  {{ with $featured }}
-    {{ $featuredURL := .RelPermalink }}
-    {{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
-      {{ $featuredURL = (.Resize "600x").RelPermalink }}
-    {{ end }}
-    <div class="{{ $articleImageClasses }}" style="background-image:url({{ $featuredURL }});"></div>
+  {{ with $featuredURL }}
+    <div class="{{ $articleImageClasses }}" style="background-image:url({{ . }});"></div>
   {{ end }}
   <div class="{{ $articleInnerClasses }}">
     <div class="items-center text-start text-xl font-semibold">