From f827f8e8d835265de5f47678b7048c7f9ba5f069 Mon Sep 17 00:00:00 2001
From: ZhenShuo Leo <98386542+ZhenShuo2021@users.noreply.github.com>
Date: Tue, 30 Sep 2025 23:09:43 +0800
Subject: [PATCH 1/4] feat: add support for imagePosition config

---
 layouts/partials/hero/background.html         | 11 ++++++++++-
 layouts/partials/hero/basic.html              | 11 ++++++++++-
 layouts/partials/hero/big.html                | 11 ++++++++++-
 layouts/partials/hero/thumbAndBackground.html | 14 ++++++++++++--
 layouts/partials/home/background.html         | 11 ++++++++++-
 layouts/partials/home/card.html               | 11 ++++++++++-
 layouts/partials/home/hero.html               | 13 ++++++++++++-
 7 files changed, 74 insertions(+), 8 deletions(-)

diff --git a/layouts/partials/hero/background.html b/layouts/partials/hero/background.html
index be9d8b78..aa2b231b 100644
--- a/layouts/partials/hero/background.html
+++ b/layouts/partials/hero/background.html
@@ -1,5 +1,6 @@
 {{ $disableImageOptimization := site.Store.Get "disableImageOptimization" }}
 
+{{ $useDefault := false }}
 {{ $featured := "" }}
 {{ $featuredURL := "" }}
 {{ with .Params.featureimage }}
@@ -25,8 +26,10 @@
   {{ $default := site.Store.Get "defaultBackgroundImage" }}
   {{ if $default.url }}
     {{ $featuredURL = $default.url }}
+    {{ $useDefault = true }}
   {{ else if $default.obj }}
     {{ $featured = $default.obj }}
+    {{ $useDefault = true }}
   {{ end }}
 {{ end }}
 
@@ -58,6 +61,11 @@
     <div id="hero" class="h-[150px] md:h-[200px]"></div>
   {{ end }}
   <div class="fixed inset-x-0 top-0 h-[800px] single_hero_background nozoom">
+    {{ $style := "" }}
+    {{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
+    {{ with $.Params.imagePosition | default $defaultPosition }}
+      {{ $style = printf "object-position: %s;" . }}
+    {{ end }}
     <img
       id="background-image"
       src="{{ . }}"
@@ -65,7 +73,8 @@
       loading="eager"
       decoding="async"
       fetchpriority="high"
-      class="absolute inset-0 w-full h-full object-cover">
+      class="absolute inset-0 w-full h-full object-cover"
+      {{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
     <div
       class="absolute inset-0 bg-gradient-to-t from-neutral dark:from-neutral-800 to-transparent mix-blend-normal"></div>
     <div
diff --git a/layouts/partials/hero/basic.html b/layouts/partials/hero/basic.html
index 76d441c6..391ce4b2 100644
--- a/layouts/partials/hero/basic.html
+++ b/layouts/partials/hero/basic.html
@@ -1,5 +1,6 @@
 {{ $disableImageOptimization := site.Store.Get "disableImageOptimization" }}
 
+{{ $useDefault := false }}
 {{ $featured := "" }}
 {{ $featuredURL := "" }}
 {{ with .Params.featureimage }}
@@ -25,8 +26,10 @@
   {{ $default := site.Store.Get "defaultBackgroundImage" }}
   {{ if $default.url }}
     {{ $featuredURL = $default.url }}
+    {{ $useDefault = true }}
   {{ else if $default.obj }}
     {{ $featured = $default.obj }}
+    {{ $useDefault = true }}
   {{ end }}
 {{ end }}
 
@@ -42,6 +45,11 @@
 {{ end }}
 
 {{ with $featuredURL }}
+  {{ $style := "" }}
+  {{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
+  {{ with $.Params.imagePosition | default $defaultPosition }}
+    {{ $style = printf "object-position: %s;" . }}
+  {{ end }}
   <div class="overflow-hidden h-36 md:h-56 lg:h-72">
     <img
       src="{{ . }}"
@@ -49,6 +57,7 @@
       loading="eager"
       decoding="async"
       fetchpriority="high"
-      class="w-full h-full nozoom object-cover">
+      class="w-full h-full nozoom object-cover"
+      {{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
   </div>
 {{ end }}
diff --git a/layouts/partials/hero/big.html b/layouts/partials/hero/big.html
index 21179cfe..3fd251d6 100644
--- a/layouts/partials/hero/big.html
+++ b/layouts/partials/hero/big.html
@@ -1,5 +1,6 @@
 {{ $disableImageOptimization := site.Store.Get "disableImageOptimization" }}
 
+{{ $useDefault := false }}
 {{ $featured := "" }}
 {{ $featuredURL := "" }}
 {{ with .Params.featureimage }}
@@ -25,8 +26,10 @@
   {{ $default := site.Store.Get "defaultBackgroundImage" }}
   {{ if $default.url }}
     {{ $featuredURL = $default.url }}
+    {{ $useDefault = true }}
   {{ else if $default.obj }}
     {{ $featured = $default.obj }}
+    {{ $useDefault = true }}
   {{ end }}
 {{ end }}
 
@@ -50,6 +53,11 @@
 {{- with .Page.Params.alt }}{{ $alt = . }}{{ end -}}
 
 {{ with $featuredURL }}
+  {{ $style := "" }}
+  {{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
+  {{ with $.Params.imagePosition | default $defaultPosition }}
+    {{ $style = printf "object-position: %s;" . }}
+  {{ end }}
   <figure>
     <img
       src="{{ . }}"
@@ -57,7 +65,8 @@
       loading="eager"
       decoding="async"
       fetchpriority="high"
-      class="w-full rounded-lg single_hero_round nozoom">
+      class="w-full rounded-lg single_hero_round nozoom"
+      {{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
     {{ if $caption }}
       <figcaption class="text-sm text-neutral-700 dark:text-neutral-400 hover:underline text-center">
         {{ $caption | markdownify }}
diff --git a/layouts/partials/hero/thumbAndBackground.html b/layouts/partials/hero/thumbAndBackground.html
index 6d80ef01..5c18b18c 100644
--- a/layouts/partials/hero/thumbAndBackground.html
+++ b/layouts/partials/hero/thumbAndBackground.html
@@ -1,6 +1,7 @@
 {{ $disableImageOptimization := site.Store.Get "disableImageOptimization" }}
 
 {{/* === Background === */}}
+{{ $useDefault := false }}
 {{ $images := .Resources.ByType "image" }}
 {{ $background := $images.GetMatch "*background*" }}
 {{ $backgroundURL := "" }}
@@ -9,8 +10,10 @@
   {{ $default := site.Store.Get "defaultBackgroundImage" }}
   {{ if $default.url }}
     {{ $backgroundURL = $default.url }}
+    {{ $useDefault = true }}
   {{ else if $default.obj }}
     {{ $background = $default.obj }}
+    {{ $useDefault = true }}
   {{ end }}
 {{ end }}
 
@@ -88,13 +91,19 @@
       loading="eager"
       decoding="async"
       fetchpriority="high"
-      class="w-full h-full nozoom object-cover">
+      class="w-full h-full nozoom object-cover"
+      {{ with $.Params.imagePositionFeature }}style="object-position: {{ . }};"{{ end }}>
   </div>
 {{ end }}
 
 
 <div class="single_hero_background nozoom fixed inset-x-0 top-0 h-[800px]">
   {{ with $backgroundURL }}
+    {{ $style := "" }}
+    {{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
+    {{ with $.Params.imagePosition | default $defaultPosition }}
+      {{ $style = printf "object-position: %s;" . }}
+    {{ end }}
     <img
       id="background-image-main"
       src="{{ . }}"
@@ -102,7 +111,8 @@
       loading="eager"
       decoding="async"
       fetchpriority="high"
-      class="absolute inset-0 h-full w-full object-cover">
+      class="absolute inset-0 h-full w-full object-cover"
+      {{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
   {{ end }}
   <div
     class="from-neutral absolute inset-0 bg-gradient-to-t to-transparent mix-blend-normal dark:from-neutral-800"></div>
diff --git a/layouts/partials/home/background.html b/layouts/partials/home/background.html
index b0090d12..88fbd868 100644
--- a/layouts/partials/home/background.html
+++ b/layouts/partials/home/background.html
@@ -5,6 +5,7 @@
     <div class="mx-auto max-w-7xl p-0">
       <div class="relative sm:overflow-hidden">
         <div class="fixed inset-x-0 top-0 -z-10">
+          {{ $useDefault := true }}
           {{ $homepageImage := "" }}
           {{ with .Site.Params.defaultBackgroundImage }}
             {{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
@@ -16,16 +17,24 @@
           {{ with .Site.Params.homepage.homepageImage }}
             {{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
               {{ $homepageImage = resources.GetRemote . }}
+              {{ $useDefault = false }}
             {{ else }}
               {{ $homepageImage = resources.Get . }}
+              {{ $useDefault = false }}
             {{ end }}
           {{ end }}
           {{ if $homepageImage }}
+            {{ $style := "" }}
+            {{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
+            {{ with $.Params.imagePosition | default $defaultPosition }}
+              {{ $style = printf "object-position: %s;" . }}
+            {{ end }}
             <img
               id="background-image"
               class="nozoom mt-0 mr-0 mb-0 ml-0 h-[1000px] w-full object-cover"
               src="{{ $homepageImage.RelPermalink }}"
-              role="presentation">
+              role="presentation"
+              {{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
             <div
               class="from-neutral absolute inset-0 h-[1000px] bg-gradient-to-t to-transparent mix-blend-normal dark:from-neutral-800"></div>
             <div
diff --git a/layouts/partials/home/card.html b/layouts/partials/home/card.html
index 1d36fd19..5600f9c6 100644
--- a/layouts/partials/home/card.html
+++ b/layouts/partials/home/card.html
@@ -14,6 +14,7 @@
       </div>
       <div class="mt-6 sm:mt-16 lg:mt-0 mx-auto max-w-xl px-4 sm:px-6 lg:mx-0 lg:max-w-none lg:py-16 lg:px-0">
         <div class="-me-48 md:-me-16 lg:relative lg:m-0 lg:h-full lg:px-0 w-full">
+          {{ $useDefault := true }}
           {{ $homepageImage := "" }}
           {{ with .Site.Params.defaultBackgroundImage }}
             {{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
@@ -25,14 +26,22 @@
           {{ with .Site.Params.homepage.homepageImage }}
             {{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
               {{ $homepageImage = resources.GetRemote . }}
+              {{ $useDefault = false }}
             {{ else }}
               {{ $homepageImage = resources.Get . }}
+              {{ $useDefault = false }}
             {{ end }}
           {{ end }}
           {{ if $homepageImage }}
+            {{ $style := "" }}
+            {{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
+            {{ with $.Params.imagePosition | default $defaultPosition }}
+              {{ $style = printf "object-position: %s;" . }}
+            {{ end }}
             <img
               class="w-full rounded-xl shadow-xl lg:absolute lg:h-full lg:w-auto lg:max-w-none"
-              src="{{ $homepageImage.RelPermalink }}">
+              src="{{ $homepageImage.RelPermalink }}"
+              {{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
           {{ end }}
         </div>
       </div>
diff --git a/layouts/partials/home/hero.html b/layouts/partials/home/hero.html
index 7fda230f..627de798 100644
--- a/layouts/partials/home/hero.html
+++ b/layouts/partials/home/hero.html
@@ -6,6 +6,7 @@
     <div class="mx-auto max-w-7xl p-0">
       <div class="relative shadow-xl sm:overflow-hidden rounded-2xl">
         <div class="absolute inset-0">
+          {{ $useDefault := true }}
           {{ $homepageImage := "" }}
           {{ with .Site.Params.defaultBackgroundImage }}
             {{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
@@ -17,12 +18,22 @@
           {{ with .Site.Params.homepage.homepageImage }}
             {{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
               {{ $homepageImage = resources.GetRemote . }}
+              {{ $useDefault = false }}
             {{ else }}
               {{ $homepageImage = resources.Get . }}
+              {{ $useDefault = false }}
             {{ end }}
           {{ end }}
           {{ if $homepageImage }}
-            <img class="h-full w-full object-cover nozoom mt-0 mr-0 mb-0 ml-0" src="{{ $homepageImage.RelPermalink }}">
+            {{ $style := "" }}
+            {{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
+            {{ with $.Params.imagePosition | default $defaultPosition }}
+              {{ $style = printf "object-position: %s;" . }}
+            {{ end }}
+            <img
+              class="h-full w-full object-cover nozoom mt-0 mr-0 mb-0 ml-0"
+              src="{{ $homepageImage.RelPermalink }}"
+              {{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
             {{ if not $disableHeroImageFilter }}
               <div
                 class="absolute inset-0 bg-gradient-to-r from-primary-500 to-secondary-600 dark:from-primary-600 dark:to-secondary-800 mix-blend-multiply"></div>

From ec8d9297f942146ab99b45ca31b8e70f4b4f0ceb Mon Sep 17 00:00:00 2001
From: ZhenShuo Leo <98386542+ZhenShuo2021@users.noreply.github.com>
Date: Tue, 30 Sep 2025 23:35:51 +0800
Subject: [PATCH 2/4] docs: add support for imagePosition config

---
 config/_default/params.toml                           | 1 +
 exampleSite/config/_default/params.toml               | 1 +
 exampleSite/content/docs/configuration/index.it.md    | 1 +
 exampleSite/content/docs/configuration/index.ja.md    | 1 +
 exampleSite/content/docs/configuration/index.md       | 1 +
 exampleSite/content/docs/configuration/index.zh-cn.md | 1 +
 exampleSite/content/docs/front-matter/index.it.md     | 7 ++++---
 exampleSite/content/docs/front-matter/index.ja.md     | 3 ++-
 exampleSite/content/docs/front-matter/index.md        | 3 ++-
 exampleSite/content/docs/front-matter/index.zh-cn.md  | 3 ++-
 10 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/config/_default/params.toml b/config/_default/params.toml
index 47f17ec2..66f17729 100644
--- a/config/_default/params.toml
+++ b/config/_default/params.toml
@@ -27,6 +27,7 @@ disableTextInHeader = false
 # defaultFeaturedImage = "IMAGE.jpg" # used as default for featured images in all articles
 # defaultSocialImage = "/android-chrome-512x512.png" # used as default for social media sharing (Open Graph and Twitter)
 hotlinkFeatureImage = false
+# imagePosition = "50% 50%"
 
 # highlightCurrentMenuArea = true
 # smartTOC = true
diff --git a/exampleSite/config/_default/params.toml b/exampleSite/config/_default/params.toml
index 97de1311..3fa5bd2c 100644
--- a/exampleSite/config/_default/params.toml
+++ b/exampleSite/config/_default/params.toml
@@ -27,6 +27,7 @@ defaultBackgroundImage = "/img/background.svg"
 defaultFeaturedImage = "/img/featured.svg"
 defaultSocialImage = "/img/blowfish_banner.png"
 hotlinkFeatureImage = false
+# imagePosition = "50% 50%"
 
 highlightCurrentMenuArea = true
 smartTOC = true
diff --git a/exampleSite/content/docs/configuration/index.it.md b/exampleSite/content/docs/configuration/index.it.md
index f0206766..86f3a81b 100644
--- a/exampleSite/content/docs/configuration/index.it.md
+++ b/exampleSite/content/docs/configuration/index.it.md
@@ -186,6 +186,7 @@ Many of the article defaults here can be overridden on a per article basis by sp
 | `defaultFeaturedImage` | _Not set_ | Default background image for all `featured` images across articles, will be overridden by a local `featured` image. |
 | `defaultSocialImage` | _Not set_ | Default image for social media sharing (Open Graph and Twitter). Will be overridden by a local `feature` image if available. |
 | `hotlinkFeatureImage` | `false` | Hotlink external images in article feature images and article cards. Those images will not be processed by Hugo. |
+| `imagePosition` | _Not set_ | Sets the position of the default image using `object-position` attribute. Valid values are as specified in the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position#try_it). |
 | `highlightCurrentMenuArea` | _Not set_ | Marks menu entries in the main menu when selected |
 | `smartTOC` | _Not set_ | Activate smart Table of Contents, items in view will be highlighted. |
 | `smartTOCHideUnfocusedChildren` | _Not set_ | When smart Table of Contents is turned on, this will hide deeper levels of the table when they are not in focus. |
diff --git a/exampleSite/content/docs/configuration/index.ja.md b/exampleSite/content/docs/configuration/index.ja.md
index 9ac72c0d..d558b2a5 100644
--- a/exampleSite/content/docs/configuration/index.ja.md
+++ b/exampleSite/content/docs/configuration/index.ja.md
@@ -186,6 +186,7 @@ Blowfish は、テーマの機能を制御する多数の設定パラメータ
 | `defaultFeaturedImage` | _未設定_ | 記事全体のすべての `featured` 画像のデフォルトの背景画像です。ローカルの `featured` 画像によってオーバーライドされます。 |
 | `defaultSocialImage` | _未設定_ | ソーシャルメディア共有（Open Graph と Twitter）用のデフォルト画像。ローカルの `featured` 画像によってオーバーライドされます。 |
 | `hotlinkFeatureImage` | `false` | 記事のアイキャッチ画像や記事カードで外部画像をホットリンクします。これらの画像は Hugo によって処理されません。 |
+| `imagePosition` | _未設定_ | `object-position` 属性を使用してデフォルト画像の位置を設定します。有効な値は [MDN ドキュメント](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position#try_it) に記載されています。 |
 | `highlightCurrentMenuArea` | _未設定_ | メインメニューのメニュー項目が選択されているときにマークを付けます。 |
 | `smartTOC` | _未設定_ | スマート目次をアクティブにします。表示されている項目が強調表示されます。 |
 | `smartTOCHideUnfocusedChildren` | _未設定_ | スマート目次がオンになっている場合、フォーカスされていないときに、テーブルのより深いレベルが非表示になります。 |
diff --git a/exampleSite/content/docs/configuration/index.md b/exampleSite/content/docs/configuration/index.md
index 8b0bd819..c0703b0f 100644
--- a/exampleSite/content/docs/configuration/index.md
+++ b/exampleSite/content/docs/configuration/index.md
@@ -192,6 +192,7 @@ Many of the article defaults here can be overridden on a per article basis by sp
 | `defaultFeaturedImage` | _Not set_ | Default background image for all `featured` images across articles, will be overridden by a local `featured` image. |
 | `defaultSocialImage` | _Not set_ | Default image for social media sharing (Open Graph and Twitter). Will be overridden by a local `feature` image. |
 | `hotlinkFeatureImage` | `false` | Hotlink external images in article feature images and article cards. Those images will not be processed by Hugo. |
+| `imagePosition` | _Not set_ | Sets the position of the default image using `object-position` attribute. Valid values are as specified in the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position#try_it). |
 | `highlightCurrentMenuArea` | _Not set_ | Marks menu entries in the main menu when selected |
 | `smartTOC` | _Not set_ | Activate smart Table of Contents, items in view will be highlighted. |
 | `smartTOCHideUnfocusedChildren` | _Not set_ | When smart Table of Contents is turned on, this will hide deeper levels of the table when they are not in focus. |
diff --git a/exampleSite/content/docs/configuration/index.zh-cn.md b/exampleSite/content/docs/configuration/index.zh-cn.md
index f87ef815..74ff19d4 100644
--- a/exampleSite/content/docs/configuration/index.zh-cn.md
+++ b/exampleSite/content/docs/configuration/index.zh-cn.md
@@ -190,6 +190,7 @@ Blowfish 提供了大量控制主题功能的配置参数，下面的表格中
 | `defaultFeaturedImage` | 无 | 设置默认背景图片，用于所有文章的`featured`图片，可以通过文章目录中的 `featured` 图片替换。 |
 | `defaultSocialImage` | 无 | 社交媒体分享（Open Graph 和 Twitter）使用的默认图片，可以通过文章目录中的 `featured` 图片替换。 |
 | `hotlinkFeatureImage` | `false` | 在文章特色图片和文章卡片中外链图片。这些图片不会被 Hugo 处理。 |
+| `imagePosition` | 无 | 使用 `object-position` 属性设置默认图像的位置。有效值如 [MDN 文档](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position#try_it) 所示。 |
 | `highlightCurrentMenuArea` | 无 | 当菜单被选择时，标记主菜单中的菜单项。 |
 | `smartTOC` | 无 | 开启智能目录，视图中的项目将会被高亮显示。 |
 | `smartTOCHideUnfocusedChildren` | 无 | 当开启智能目录，如果目录级别不再被聚焦时，将会隐藏更深层次的目录。 |
diff --git a/exampleSite/content/docs/front-matter/index.it.md b/exampleSite/content/docs/front-matter/index.it.md
index 8ef94840..774ed64c 100644
--- a/exampleSite/content/docs/front-matter/index.it.md
+++ b/exampleSite/content/docs/front-matter/index.it.md
@@ -28,10 +28,11 @@ I valori predefiniti dei parametri del front metter vengono ereditati dalla [con
 | `showAuthor` | `article.showAuthor` | Se la casella dell'autore predefinito viene visualizzata o meno nel piè di pagina dell'articolo. |
 | `authors` | _Not set_ | Matrice di valori per gli autori, se impostata sovrascrive le impostazioni di "showAuthor" per la pagina o il sito. Utilizzato nella funzionalità per più autori, controlla [questa pagina]({{< ref "multi-author" >}}) per maggiori dettagli su come configurare tale funzionalità. |
 | `showAuthorsBadges` | `article.showAuthorsBadges` | Se le tassonomie degli "autori" vengono visualizzate nell'articolo o nell'intestazione dell'elenco. Ciò richiede l'impostazione di "autori multipli" e la tassonomia degli "autori". Controlla [questa pagina]({{< ref "multi-author" >}}) per maggiori dettagli su come configurare questa funzione. |
-| `featureimage`                | _Not set_                                                                                                       | URL esterno per l'immagine in primo piano
-| `featureimagecaption`         | _Not set_                                                                                                       | Didascalia per l'immagine in primo piano. Visualizzato solo in heroStyle "big".
+| `featureimage` | _Not set_ | Link per l'immagine in primo piano |
+| `featureimagecaption` | _Not set_ | Didascalia per l'immagine in primo piano. Visualizzato solo in heroStyle "big". |
 | `showHero` | `article.showHero` | Se l'immagine in miniatura verrà mostrata come immagine hero all'interno della pagina dell'articolo. |
-| `heroStyle` | `article.heroStyle` | Stile per visualizzare l'immagine hero, le opzioni valide sono: `basic`, `big`, ` background`, `thumbAndBackground`. |
+| `heroStyle` | `article.heroStyle` | Stile per visualizzare l'immagine hero, le opzioni valide sono: `basic`, `big`, `background`, `thumbAndBackground`. |
+| `imagePosition` | _Not set_ | Imposta la posizione dell'immagine in evidenza utilizzando l'attributo `object-position`. I valori validi sono specificati nella [documentazione MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position#try_it). |
 | `showBreadcrumbs` | `article.showBreadcrumbs` or `list.showBreadcrumbs` | Se i breadcrumb vengono visualizzati nell'articolo o nell'intestazione dell'elenco. |
 | `showDate` | `article.showDate` | Se viene visualizzata o meno la data dell'articolo. La data viene impostata utilizzando il parametro "data". |
 | `showDateUpdated` | `article.showDateUpdated` | Se viene visualizzata o meno la data di aggiornamento dell'articolo. La data viene impostata utilizzando il parametro "lastmod". |
diff --git a/exampleSite/content/docs/front-matter/index.ja.md b/exampleSite/content/docs/front-matter/index.ja.md
index 1ca1f6e8..48a7e033 100644
--- a/exampleSite/content/docs/front-matter/index.ja.md
+++ b/exampleSite/content/docs/front-matter/index.ja.md
@@ -29,10 +29,11 @@ series_order: 7
 | `showAuthorBottom` | `article.showAuthorBottom` | 著者ボックスは、各ページの上部ではなく下部に表示されます。 |
 | `authors` | _未設定_ | 著者の値の配列。設定されている場合、ページまたはサイトの `showAuthor` 設定を上書きします。複数人の著者機能で使用されます。この機能の設定方法の詳細については、[このページ]({{< ref "multi-author" >}})をご覧ください。 |
 | `showAuthorsBadges` | `article.showAuthorsBadges` | 記事またはリストヘッダーに `authors` タクソノミーを表示するかどうか。これには、`複数人の著者` と `authors` タクソノミーの設定が必要です。この機能の設定方法の詳細については、[このページ]({{< ref "multi-author" >}})をご覧ください。 |
-| `featureimage` | _未設定_ | フィーチャー画像の外部 URL。 |
+| `featureimage` | _未設定_ | フィーチャー画像の外部リンク。 |
 | `featureimagecaption` | _未設定_ | フィーチャー画像のキャプション。heroStyle `big` でのみ表示されます。 |
 | `showHero` | `article.showHero` | 記事ページ内でサムネイル画像をヒーロー画像として表示するかどうか。 |
 | `heroStyle` | `article.heroStyle` | ヒーロー画像の表示スタイル。有効なオプションは、`basic`、`big`、`background`、`thumbAndBackground` です。 |
+| `imagePosition` | _未設定_ | `object-position` 属性を使用してフィーチャー画像の位置を設定します。有効な値は [MDN ドキュメント](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position#try_it) に記載されています。 |
 | `showBreadcrumbs` | `article.showBreadcrumbs` <br/>または `list.showBreadcrumbs` | 記事またはリストヘッダーにパンくずリストを表示するかどうか。 |
 | `showDate` | `article.showDate` | 記事の日付を表示するかどうか。日付は `date` パラメータを使用して設定されます。 |
 | `showDateUpdated` | `article.showDateUpdated` | 記事が更新された日付を表示するかどうか。日付は `lastmod` パラメータを使用して設定されます。 |
diff --git a/exampleSite/content/docs/front-matter/index.md b/exampleSite/content/docs/front-matter/index.md
index 1701bc66..5d02d074 100644
--- a/exampleSite/content/docs/front-matter/index.md
+++ b/exampleSite/content/docs/front-matter/index.md
@@ -29,10 +29,11 @@ Front matter parameter default values are inherited from the theme's [base confi
 | `showAuthorBottom` | `article.showAuthorBottom` | Author boxes are displayed at the bottom of each page instead of the top. |
 | `authors` | _Not set_ | Array of values for authors, if set it overrides `showAuthor` settings for page or site. Used on the multiple authors feature, check [this page]({{< ref "multi-author" >}}) for more details on how to configure that feature. |
 | `showAuthorsBadges` | `article.showAuthorsBadges` | Whether the `authors` taxonomies are are displayed in the article or list header. This requires the setup of `multiple authors` and the `authors` taxonomy. Check [this page]({{< ref "multi-author" >}}) for more details on how to configure that feature. |
-| `featureimage` | _Not set_ | External URL for feature image |
+| `featureimage` | _Not set_ | Link for feature image |
 | `featureimagecaption` | _Not set_ | Caption for feature image. Only displayed in heroStyle `big` |
 | `showHero` | `article.showHero` | Whether the thumbnail image will be shown as a hero image within the article page. |
 | `heroStyle` | `article.heroStyle` | Style to display the hero image, valid options are: `basic`, `big`, `background`, `thumbAndBackground`. |
+| `imagePosition` | _Not set_ | Sets the position of the feature image using `object-position` attribute. Valid values are as specified in the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position#try_it). |
 | `showBreadcrumbs` | `article.showBreadcrumbs` or `list.showBreadcrumbs` | Whether the breadcrumbs are displayed in the article or list header. |
 | `showDate` | `article.showDate` | Whether or not the article date is displayed. The date is set using the `date` parameter. |
 | `showDateUpdated` | `article.showDateUpdated` | Whether or not the date the article was updated is displayed. The date is set using the `lastmod` parameter. |
diff --git a/exampleSite/content/docs/front-matter/index.zh-cn.md b/exampleSite/content/docs/front-matter/index.zh-cn.md
index 5ac262d4..21007838 100644
--- a/exampleSite/content/docs/front-matter/index.zh-cn.md
+++ b/exampleSite/content/docs/front-matter/index.zh-cn.md
@@ -29,10 +29,11 @@ front matter 参数中的默认值是从[基础配置]({{< ref "configuration" >
 | `showAuthorBottom` | `article.showAuthorBottom` | 作者框显示在每页的底部而不是顶部。 |
 | `authors` | 无 | 用于展示多创作者的数组，如果设置了将会覆盖 `showAuthor` 设置。这里使用了多作者的特性，查看[这个页面]({{< ref "multi-author" >}})来获取更多信息。 |
 | `showAuthorsBadges` | `article.showAuthorsBadges` | 是否在文章和列表页展示`authors`作者分类。想是它生效需要开启`multiple authors`多创作者和 `authors` 作者分类。 查看[这个页面]({{< ref "multi-author" >}})来获取更多信息。 |
-| `featureimage` | 无 | 基于外部 URL 的特征图片链接。 |
+| `featureimage` | 无 | 基于连结的特征图片链接。 |
 | `featureimagecaption` | 无 | 特征图片的说明，仅在 hero 样式的 `big` 风格下展示。 |
 | `showHero` | `article.showHero` | 是否在文章页面将所裸土作为文章页面内的 hero 图片显示。 |
 | `heroStyle` | `article.heroStyle` | hero 图片的风格，合法的值有： `basic`、`big`、`background`、`thumbAndBackground`。 |
+| `imagePosition` | 无 | 使用 `object-position` 属性设置特色图片的位置。有效值如 [MDN 文档](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position#try_it) 所示。 |
 | `showBreadcrumbs` | `article.showBreadcrumbs` or `list.showBreadcrumbs` | 是否在文章或列表页面显示面包屑导航。 |
 | `showDate` | `article.showDate` | 是否显示文章的日期。具体日期使用 `date` 参数设置。 |
 | `showDateUpdated` | `article.showDateUpdated` | 是否显示文章的更新日期。具体日期使用 `lastmod` 参数设置。 |

From a27d65ad3681d309447940a37360afe91879f902 Mon Sep 17 00:00:00 2001
From: ZhenShuo Leo <98386542+ZhenShuo2021@users.noreply.github.com>
Date: Wed, 8 Oct 2025 13:06:24 +0800
Subject: [PATCH 3/4] fix(article-link): replace figure tag to div

this is not needed for decorative images
---
 layouts/partials/article-link/_shortcode.html   | 10 +++++-----
 layouts/partials/article-link/card-related.html |  4 ++--
 layouts/partials/article-link/card.html         |  4 ++--
 layouts/partials/article-link/simple.html       | 10 +++++-----
 4 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/layouts/partials/article-link/_shortcode.html b/layouts/partials/article-link/_shortcode.html
index 42baaa55..897d4bcc 100644
--- a/layouts/partials/article-link/_shortcode.html
+++ b/layouts/partials/article-link/_shortcode.html
@@ -14,16 +14,16 @@
 {{ $disableImageOptimization := site.Store.Get "disableImageOptimization" }}
 
 {{ $cardClasses := "flex flex-col md:flex-row relative" }}
-{{ $figureClasses := "" }}
+{{ $imgWrapperClasses := "" }}
 {{ $cardContentClasses := "" }}
 
 {{ if site.Params.list.showCards }}
   {{ $cardClasses = printf "%s overflow-hidden rounded-md border-2 border-neutral-200 dark:border-neutral-700" $cardClasses }}
-  {{ $figureClasses = "" }}
+  {{ $imgWrapperClasses = "" }}
   {{ $cardContentClasses = printf "%s p-2.5 pl-4 pb-0" $cardContentClasses }}
 {{ else }}
   {{ $cardClasses = printf "%s" $cardClasses }}
-  {{ $figureClasses = printf "%s thumbnail-shadow md:mr-7" $figureClasses }}
+  {{ $imgWrapperClasses = printf "%s thumbnail-shadow md:mr-7" $imgWrapperClasses }}
   {{ $cardContentClasses = printf "%s mt-3 md:mt-0" $cardContentClasses }}
 {{ end }}
 
@@ -82,14 +82,14 @@
 
 <article class="{{ $cardClasses }}">
   {{ with $featuredURL }}
-    <figure class="not-prose flex-none relative overflow-hidden {{ $figureClasses }} thumbnail--simple">
+    <div class="flex-none relative overflow-hidden {{ $imgWrapperClasses }} thumbnail--simple">
       <img
         src="{{ . }}"
         alt=""
         loading="lazy"
         decoding="async"
         class="not-prose absolute inset-0 w-full h-full object-cover">
-    </figure>
+    </div>
   {{ end }}
   <div class="{{ $cardContentClasses }}">
     <header 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 5ca00aba..6db55a4d 100644
--- a/layouts/partials/article-link/card-related.html
+++ b/layouts/partials/article-link/card-related.html
@@ -53,7 +53,7 @@
 <article
   class="relative min-h-full min-w-full overflow-hidden rounded border border-2 border-neutral-200 shadow-2xl dark:border-neutral-700">
   {{ with $featuredURL }}
-    <figure class="not-prose flex-none relative overflow-hidden thumbnail--related">
+    <div class="flex-none relative overflow-hidden thumbnail--related">
       <img
         src="{{ . }}"
         alt=""
@@ -61,7 +61,7 @@
         decoding="async"
         fetchpriority="low"
         class="not-prose absolute inset-0 w-full h-full object-cover">
-    </figure>
+    </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 02dce92f..386f1e57 100644
--- a/layouts/partials/article-link/card.html
+++ b/layouts/partials/article-link/card.html
@@ -57,14 +57,14 @@
 <article
   class="relative min-h-full min-w-full overflow-hidden rounded border border-2 border-neutral-200 shadow-2xl dark:border-neutral-700">
   {{ with $featuredURL }}
-    <figure class="not-prose flex-none relative overflow-hidden thumbnail--card">
+    <div class="flex-none relative overflow-hidden thumbnail--card">
       <img
         src="{{ . }}"
         alt=""
         loading="lazy"
         decoding="async"
         class="not-prose absolute inset-0 w-full h-full object-cover">
-    </figure>
+    </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 72bf0772..4c8c00e4 100644
--- a/layouts/partials/article-link/simple.html
+++ b/layouts/partials/article-link/simple.html
@@ -7,16 +7,16 @@
 {{ $disableImageOptimization := site.Store.Get "disableImageOptimization" }}
 
 {{ $cardClasses := "flex flex-col md:flex-row relative" }}
-{{ $figureClasses := "" }}
+{{ $imgWrapperClasses := "" }}
 {{ $cardContentClasses := "" }}
 
 {{ if site.Params.list.showCards }}
   {{ $cardClasses = printf "%s overflow-hidden rounded-md border-2 border-neutral-200 dark:border-neutral-700" $cardClasses }}
-  {{ $figureClasses = "" }}
+  {{ $imgWrapperClasses = "" }}
   {{ $cardContentClasses = printf "%s p-4" $cardContentClasses }}
 {{ else }}
   {{ $cardClasses = $cardClasses }}
-  {{ $figureClasses = printf "%s thumbnail-shadow md:mr-7" $figureClasses }}
+  {{ $imgWrapperClasses = printf "%s thumbnail-shadow md:mr-7" $imgWrapperClasses }}
   {{ $cardContentClasses = printf "%s mt-3 md:mt-0" $cardContentClasses }}
 {{ end }}
 
@@ -75,14 +75,14 @@
 
 <article class="{{ $cardClasses }}">
   {{ with $featuredURL }}
-    <figure class="not-prose flex-none relative overflow-hidden {{ $figureClasses }} thumbnail--simple">
+    <div class="flex-none relative overflow-hidden {{ $imgWrapperClasses }} thumbnail--simple">
       <img
         src="{{ . }}"
         alt=""
         loading="lazy"
         decoding="async"
         class="not-prose absolute inset-0 w-full h-full object-cover">
-    </figure>
+    </div>
   {{ end }}
   <div class="{{ $cardContentClasses }}">
     <header class="items-center text-start text-xl font-semibold">

From 3918571644f4f2a0fe22ae43e780429001fb6367 Mon Sep 17 00:00:00 2001
From: ZhenShuo Leo <98386542+ZhenShuo2021@users.noreply.github.com>
Date: Wed, 8 Oct 2025 13:12:49 +0800
Subject: [PATCH 4/4] chore(article-link): use old naming of css class name

though the new thumbnail--xxx naming is cleaner
but this kind of change should be postponed until a major release
---
 assets/css/compiled/main.css                    | 8 ++++----
 assets/css/main.css                             | 8 ++++----
 layouts/partials/article-link/_shortcode.html   | 2 +-
 layouts/partials/article-link/card-related.html | 2 +-
 layouts/partials/article-link/card.html         | 2 +-
 layouts/partials/article-link/simple.html       | 2 +-
 layouts/partials/term-link/card.html            | 2 +-
 7 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/assets/css/compiled/main.css b/assets/css/compiled/main.css
index 44a09a62..0d7c2c6f 100644
--- a/assets/css/compiled/main.css
+++ b/assets/css/compiled/main.css
@@ -3779,19 +3779,19 @@ pre {
   width: 100%;
   height: 100%;
 }
-.thumbnail--card {
+.thumbnail_card {
   min-width: 300px;
   height: 200px;
 }
-.thumbnail--related {
+.thumbnail_card_related {
   height: 150px;
 }
-.thumbnail--simple {
+.thumbnail {
   width: 300px;
   min-height: 180px;
 }
 @media (width < 853px) {
-  .thumbnail--simple {
+  .thumbnail {
     width: 100%;
   }
 }
diff --git a/assets/css/main.css b/assets/css/main.css
index 577c60ec..e3f35ecf 100644
--- a/assets/css/main.css
+++ b/assets/css/main.css
@@ -177,22 +177,22 @@ pre {
   height: 100%;
 }
 
-.thumbnail--card {
+.thumbnail_card {
   min-width: 300px;
   height: 200px;
 }
 
-.thumbnail--related {
+.thumbnail_card_related {
   height: 150px;
 }
 
-.thumbnail--simple {
+.thumbnail {
   width: 300px;
   min-height: 180px;
 }
 
 @variant max-md {
-  .thumbnail--simple {
+  .thumbnail {
     width: 100%;
   }
 }
diff --git a/layouts/partials/article-link/_shortcode.html b/layouts/partials/article-link/_shortcode.html
index 897d4bcc..a803ded0 100644
--- a/layouts/partials/article-link/_shortcode.html
+++ b/layouts/partials/article-link/_shortcode.html
@@ -82,7 +82,7 @@
 
 <article class="{{ $cardClasses }}">
   {{ with $featuredURL }}
-    <div class="flex-none relative overflow-hidden {{ $imgWrapperClasses }} thumbnail--simple">
+    <div class="flex-none relative overflow-hidden {{ $imgWrapperClasses }} thumbnail">
       <img
         src="{{ . }}"
         alt=""
diff --git a/layouts/partials/article-link/card-related.html b/layouts/partials/article-link/card-related.html
index 6db55a4d..ae86759e 100644
--- a/layouts/partials/article-link/card-related.html
+++ b/layouts/partials/article-link/card-related.html
@@ -53,7 +53,7 @@
 <article
   class="relative min-h-full min-w-full overflow-hidden rounded border border-2 border-neutral-200 shadow-2xl dark:border-neutral-700">
   {{ with $featuredURL }}
-    <div class="flex-none relative overflow-hidden thumbnail--related">
+    <div class="flex-none relative overflow-hidden thumbnail_card_related">
       <img
         src="{{ . }}"
         alt=""
diff --git a/layouts/partials/article-link/card.html b/layouts/partials/article-link/card.html
index 386f1e57..110dcd18 100644
--- a/layouts/partials/article-link/card.html
+++ b/layouts/partials/article-link/card.html
@@ -57,7 +57,7 @@
 <article
   class="relative min-h-full min-w-full overflow-hidden rounded border border-2 border-neutral-200 shadow-2xl dark:border-neutral-700">
   {{ with $featuredURL }}
-    <div class="flex-none relative overflow-hidden thumbnail--card">
+    <div class="flex-none relative overflow-hidden thumbnail_card">
       <img
         src="{{ . }}"
         alt=""
diff --git a/layouts/partials/article-link/simple.html b/layouts/partials/article-link/simple.html
index 4c8c00e4..3255e136 100644
--- a/layouts/partials/article-link/simple.html
+++ b/layouts/partials/article-link/simple.html
@@ -75,7 +75,7 @@
 
 <article class="{{ $cardClasses }}">
   {{ with $featuredURL }}
-    <div class="flex-none relative overflow-hidden {{ $imgWrapperClasses }} thumbnail--simple">
+    <div class="flex-none relative overflow-hidden {{ $imgWrapperClasses }} thumbnail">
       <img
         src="{{ . }}"
         alt=""
diff --git a/layouts/partials/term-link/card.html b/layouts/partials/term-link/card.html
index eb2fe80f..8267b121 100644
--- a/layouts/partials/term-link/card.html
+++ b/layouts/partials/term-link/card.html
@@ -28,7 +28,7 @@
 <div class="min-w-full">
   <div class="border-neutral-200 dark:border-neutral-700 border-2 rounded overflow-hidden shadow-2xl relative">
     {{ with $featuredURL }}
-      <figure class="not-prose flex-none relative overflow-hidden thumbnail--card">
+      <figure class="not-prose flex-none relative overflow-hidden thumbnail_card">
         <img
           src="{{ . }}"
           alt="{{ $.Page.Title }}"