From bec38c87596c0ca09df3747f081d425e624ba257 Mon Sep 17 00:00:00 2001
From: George Cushen <gcushen@users.noreply.github.com>
Date: Mon, 18 Aug 2025 02:43:55 +0100
Subject: [PATCH] feat: improve avatar quality and add customizable sizing
 options

Resolves #3123

## What Changed

**Avatar Quality Improvements:**
- Generate avatars at 2x resolution for crisp display on high-DPI screens
- Updated Hugo imaging config with quality: 90, lanczos resampling, and picture hint
- Improved WebP compression quality across all avatar locations

**New Customization Parameters:**
- Added design.avatar.size with 5 options: small (150px), medium (200px), large (320px), xl (400px), xxl (500px)
- Added design.avatar.shape with 3 options: circle (default), square, rounded
- Sizing aligned with 2025 social media standards (LinkedIn/X: 400px, Instagram: 320px, TikTok: 200px)

**Updated Templates:**
- Enhanced resume-biography.html and resume-biography-3.html with flexible parameter system
- Updated all starter templates (academic-cv, resume, blog, link-in-bio) with example configurations
- Improved avatar CSS for dynamic sizing control
---
 .github/ISSUE_TEMPLATE/config.yml             | 37 ++++++++++++++-----
 .../assets/css/blox/biography.css             |  7 +---
 modules/blox-tailwind/hugo.yaml               |  6 +++
 .../_partials/blox/resume-biography-3.html    | 24 +++++++++---
 .../_partials/blox/resume-biography.html      | 24 +++++++++---
 .../layouts/_partials/page_author_card.html   |  2 +-
 .../layouts/_partials/site_head.html          |  2 +-
 .../layouts/_partials/views/article-grid.html |  2 +-
 modules/blox-tailwind/layouts/single.html     |  2 +-
 .../academic-cv/config/_default/hugo.yaml     |  3 +-
 starters/academic-cv/content/_index.md        |  4 ++
 starters/blog/config/_default/hugo.yaml       |  3 +-
 starters/blog/content/_index.md               |  4 ++
 .../documentation/config/_default/hugo.yaml   |  3 +-
 .../landing-page/config/_default/hugo.yaml    |  3 +-
 .../link-in-bio/config/_default/hugo.yaml     |  3 +-
 starters/link-in-bio/content/_index.md        |  4 ++
 starters/resume/config/_default/hugo.yaml     |  3 +-
 starters/resume/content/_index.md             |  4 ++
 19 files changed, 106 insertions(+), 34 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 764dfec0..d835a755 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,14 +1,33 @@
 blank_issues_enabled: false
 contact_links:
-  - name: Questions
+  - name: 💬 Contributing chat (Discord)
     url: https://discord.gg/z8wNYzb
-    about: Chat live with the Hugo Blox Builder community on Discord.
-  - name: Discussions
-    url: https://github.com/HugoBlox/hugo-blox-builder/discussions
-    about: Discuss Hugo Blox Builder on the GitHub Discussions forum
-  - name: Troubleshooting Guide
+    about: Ask quick questions in the Contributing channel and coordinate with Geo & contributors.
+
+  - name: 🧪 Troubleshooting Guide
     url: https://docs.hugoblox.com/reference/troubleshooting/
-    about: Solve common issues fast.
-  - name: Documentation
+    about: Fix common issues fast and follow the reproducible-issue checklist before filing.
+
+  - name: 🏷️ Help-wanted issues (good first tasks)
+    url: https://github.com/HugoBlox/hugo-blox-builder/labels/help%20wanted
+    about: Pick a bite-sized task and open your first PR in minutes.
+
+  - name: 🧭 Contributing Guide
+    url: https://github.com/HugoBlox/hugo-blox-builder/blob/main/CONTRIBUTING.md
+    about: How we work, environment setup, style, and PR tips.
+
+  - name: 🧵 Discussions (Q&A, ideas)
+    url: https://github.com/HugoBlox/hugo-blox-builder/discussions
+    about: Ask for help, propose features, or share learnings.
+
+  - name: 📚 Documentation
     url: https://docs.hugoblox.com/
-    about: Review the documentation
+    about: Explore all Hugo Blox docs, tutorials, and references.
+
+  - name: 💚 Support Hugo Blox (All Access)
+    url: https://hugoblox.com/all-access
+    about: Too busy to contribute? Support development and get lifetime template updates.
+
+  - name: 🫶 Sponsor on GitHub
+    url: https://github.com/sponsors/gcushen
+    about: Prefer monthly or one-time sponsorship via GitHub.
diff --git a/modules/blox-tailwind/assets/css/blox/biography.css b/modules/blox-tailwind/assets/css/blox/biography.css
index 911e596a..806d775f 100644
--- a/modules/blox-tailwind/assets/css/blox/biography.css
+++ b/modules/blox-tailwind/assets/css/blox/biography.css
@@ -5,13 +5,11 @@
     position: relative;
   }
 
-  /* Custom avatar size on homepage */
+  /* Custom avatar size on homepage - size controlled by template params */
 
   .avatar {
     width: auto;
     height: auto;
-    max-width: 225px;
-    max-height: 225px;
     object-fit: cover;
   }
 
@@ -97,8 +95,7 @@
 
 .avatar-wrapper {
   position: relative;
-  width: 150px; /* Match image size in about.avatar widget */
-  height: 150px;
+  /* width and height controlled by template params */
   margin-left: auto;
   margin-right: auto;
 }
diff --git a/modules/blox-tailwind/hugo.yaml b/modules/blox-tailwind/hugo.yaml
index a87d7463..b530c50c 100644
--- a/modules/blox-tailwind/hugo.yaml
+++ b/modules/blox-tailwind/hugo.yaml
@@ -102,6 +102,12 @@ outputFormats:
     baseName: backlinks
     isPlainText: true
     notAlternative: true
+imaging:
+  # High quality defaults for crisp avatar display
+  quality: 90
+  resampleFilter: lanczos
+  anchor: smart
+  hint: picture
 params:
   locale:
     date_format: 'Jan 2, 2006'
diff --git a/modules/blox-tailwind/layouts/_partials/blox/resume-biography-3.html b/modules/blox-tailwind/layouts/_partials/blox/resume-biography-3.html
index db12d682..9aa9b7c9 100644
--- a/modules/blox-tailwind/layouts/_partials/blox/resume-biography-3.html
+++ b/modules/blox-tailwind/layouts/_partials/blox/resume-biography-3.html
@@ -15,7 +15,20 @@
 {{end}}
 {{ $person := $person_page.Params }}
 {{ $avatar := ($person_page.Resources.ByType "image").GetMatch "*avatar*" }}
-{{ $avatar_shape := site.Params.features.avatar.shape | default "circle" }}
+
+{{/* Avatar customization parameters */}}
+{{ $avatar_size := $block.design.avatar.size | default "medium" }}
+{{ $avatar_shape := $block.design.avatar.shape | default "circle" }}
+
+{{/* Size mappings optimized for 2025 standards: display_size -> [display_px, generation_px] */}}
+{{ $size_map := dict "small" (slice "150" "300") "medium" (slice "200" "400") "large" (slice "320" "640") "xl" (slice "400" "800") "xxl" (slice "500" "1000") }}
+{{ $size_config := index $size_map $avatar_size | default (index $size_map "medium") }}
+{{ $display_size := index $size_config 0 }}
+{{ $generation_size := index $size_config 1 }}
+
+{{/* Shape class mappings */}}
+{{ $shape_classes := dict "circle" "rounded-full" "square" "rounded-none" "rounded" "rounded-lg" }}
+{{ $shape_class := index $shape_classes $avatar_shape | default "rounded-full" }}
 
 
 <div class="resume-biography px-3 flex flex-col md:flex-row justify-center gap-12">
@@ -42,10 +55,11 @@
   <div id="profile" class="flex justify-center items-center flex-col">
     {{ if $avatar }}
 
-    <div class="avatar-wrapper {{ if $img }}-mt-[105px]{{else}}mt-10{{end}}">
-      {{ $avatar_image := $avatar.Fill "150x150 Center" }}
-      <img class="avatar rounded-full bg-white dark:bg-gray-800 p-1" src="{{ $avatar_image.RelPermalink }}" alt="{{$person_page.Title}}"
-           width="{{ $avatar_image.Width }}" height="{{ $avatar_image.Height }}">
+    <div class="avatar-wrapper {{ if $img }}-mt-[105px]{{else}}mt-10{{end}}" style="width: {{$display_size}}px; height: {{$display_size}}px;">
+      {{ $avatar_image := $avatar.Fill (printf "%sx%s Center" $generation_size $generation_size) }}
+      <img class="avatar {{$shape_class}} bg-white dark:bg-gray-800 p-1" src="{{ $avatar_image.RelPermalink }}" alt="{{$person_page.Title}}"
+           width="{{$display_size}}" height="{{$display_size}}"
+           style="width: {{$display_size}}px; height: {{$display_size}}px; object-fit: cover;">
       {{with $person.status.icon}}<span class="avatar-emoji">{{.|emojify}}</span>{{end}}
     </div>
     {{ end }}
diff --git a/modules/blox-tailwind/layouts/_partials/blox/resume-biography.html b/modules/blox-tailwind/layouts/_partials/blox/resume-biography.html
index 22112ce9..c3ea123c 100644
--- a/modules/blox-tailwind/layouts/_partials/blox/resume-biography.html
+++ b/modules/blox-tailwind/layouts/_partials/blox/resume-biography.html
@@ -15,7 +15,20 @@
 {{end}}
 {{ $person := $person_page.Params }}
 {{ $avatar := ($person_page.Resources.ByType "image").GetMatch "*avatar*" }}
-{{ $avatar_shape := site.Params.features.avatar.shape | default "circle" }}
+
+{{/* Avatar customization parameters */}}
+{{ $avatar_size := $block.design.avatar.size | default "medium" }}
+{{ $avatar_shape := $block.design.avatar.shape | default "circle" }}
+
+{{/* Size mappings optimized for 2025 standards: display_size -> [display_px, generation_px] */}}
+{{ $size_map := dict "small" (slice "150" "300") "medium" (slice "200" "400") "large" (slice "320" "640") "xl" (slice "400" "800") "xxl" (slice "500" "1000") }}
+{{ $size_config := index $size_map $avatar_size | default (index $size_map "medium") }}
+{{ $display_size := index $size_config 0 }}
+{{ $generation_size := index $size_config 1 }}
+
+{{/* Shape class mappings */}}
+{{ $shape_classes := dict "circle" "rounded-full" "square" "rounded-none" "rounded" "rounded-lg" }}
+{{ $shape_class := index $shape_classes $avatar_shape | default "rounded-full" }}
 
 {{ $img := "" }}
 {{with $block.design.banner.filename}}
@@ -38,10 +51,11 @@
 <div id="profile" class="resume-biography flex justify-center items-center flex-col dark:text-white">
   {{ if $avatar }}
 
-  <div class="avatar-wrapper {{ if $img }}-mt-[105px]{{else}}mt-10{{end}}">
-    {{ $avatar_image := $avatar.Fill "150x150 Center" }}
-    <img class="avatar rounded-full bg-white dark:bg-gray-800 p-1" src="{{ $avatar_image.RelPermalink }}" alt="{{$person_page.Title}}"
-         width="{{ $avatar_image.Width }}" height="{{ $avatar_image.Height }}">
+  <div class="avatar-wrapper {{ if $img }}-mt-[105px]{{else}}mt-10{{end}}" style="width: {{$display_size}}px; height: {{$display_size}}px;">
+    {{ $avatar_image := $avatar.Fill (printf "%sx%s Center" $generation_size $generation_size) }}
+    <img class="avatar {{$shape_class}} bg-white dark:bg-gray-800 p-1" src="{{ $avatar_image.RelPermalink }}" alt="{{$person_page.Title}}"
+         width="{{$display_size}}" height="{{$display_size}}"
+         style="width: {{$display_size}}px; height: {{$display_size}}px; object-fit: cover;">
     {{with $person.status.icon}}<span class="avatar-emoji">{{.|emojify}}</span>{{end}}
   </div>
   {{ end }}
diff --git a/modules/blox-tailwind/layouts/_partials/page_author_card.html b/modules/blox-tailwind/layouts/_partials/page_author_card.html
index ca05b767..19b7214c 100644
--- a/modules/blox-tailwind/layouts/_partials/page_author_card.html
+++ b/modules/blox-tailwind/layouts/_partials/page_author_card.html
@@ -15,7 +15,7 @@
 
 <div class="flex pt-12 pb-4">
   {{ if $avatar }}
-  {{ $authorImage := $avatar.Fill "192x192 Center" }}
+  {{ $authorImage := $avatar.Fill "384x384 Center" }}
   <img
     class="mr-4 h-24 w-24 {{if ne $avatar_shape "square"}}rounded-full{{end}}"
     width="96"
diff --git a/modules/blox-tailwind/layouts/_partials/site_head.html b/modules/blox-tailwind/layouts/_partials/site_head.html
index b7435441..a5ac3962 100644
--- a/modules/blox-tailwind/layouts/_partials/site_head.html
+++ b/modules/blox-tailwind/layouts/_partials/site_head.html
@@ -149,7 +149,7 @@
   {{ $twitter_card := "summary_large_image" }}
   {{ if (and (eq .Kind "term") $avatar_image) }}
     {{/* Match image processing in About widget to prevent generating more images than necessary. */}}
-    {{ $og_image = ($avatar_image.Fill "270x270 Center").Permalink }}
+    {{ $og_image = ($avatar_image.Fill "540x540 Center").Permalink }}
     {{ $twitter_card = "summary" }}
   {{ else if $featured_image }}
     {{ $og_image = $featured_image.Permalink }}
diff --git a/modules/blox-tailwind/layouts/_partials/views/article-grid.html b/modules/blox-tailwind/layouts/_partials/views/article-grid.html
index 254ea6ab..3bc76fb1 100644
--- a/modules/blox-tailwind/layouts/_partials/views/article-grid.html
+++ b/modules/blox-tailwind/layouts/_partials/views/article-grid.html
@@ -70,7 +70,7 @@
               <div class="relative h-5 w-5 flex-shrink-0">
               {{ $avatar := (.Resources.ByType "image").GetMatch "*avatar*" }}
               {{ if $avatar }}
-              {{ $authorImage := $avatar.Process "Fill 50x50 Center 95 webp" }}
+              {{ $authorImage := $avatar.Process "Fill 100x100 Center webp" }}
               <img alt="avatar"
                    class="rounded-full object-cover"
                    data-nimg="fill"
diff --git a/modules/blox-tailwind/layouts/single.html b/modules/blox-tailwind/layouts/single.html
index 684ca2a0..26add2ca 100644
--- a/modules/blox-tailwind/layouts/single.html
+++ b/modules/blox-tailwind/layouts/single.html
@@ -48,7 +48,7 @@
           {{ end }}
           <div class="group inline-flex items-center text-current gap-x-1.5 mx-1">
             {{ with $avatar }}
-            {{ $avatar = $avatar.Process "Fill 50x50 Center webp" }}
+            {{ $avatar = $avatar.Process "Fill 100x100 Center webp" }}
             <img src="{{ $avatar.RelPermalink }}" alt="{{ $author_page.Title }}" class="inline-block h-4 w-4 rounded-full border border-current" loading="lazy" />
             {{ end }}
             <div {{if $author_page.Params.website}}class="group-hover:underline"{{end}}>{{ $author_page.Title }}</div>
diff --git a/starters/academic-cv/config/_default/hugo.yaml b/starters/academic-cv/config/_default/hugo.yaml
index 836e88d9..19769c0b 100644
--- a/starters/academic-cv/config/_default/hugo.yaml
+++ b/starters/academic-cv/config/_default/hugo.yaml
@@ -39,8 +39,9 @@ outputs:
   section: [HTML, RSS]
 imaging:
   resampleFilter: lanczos
-  quality: 80
+  quality: 90
   anchor: smart
+  hint: picture
 timeout: 600000
 taxonomies:
   author: authors
diff --git a/starters/academic-cv/content/_index.md b/starters/academic-cv/content/_index.md
index d2dbd2e7..5b40ea72 100644
--- a/starters/academic-cv/content/_index.md
+++ b/starters/academic-cv/content/_index.md
@@ -20,6 +20,10 @@ sections:
         url: uploads/resume.pdf
     design:
       css_class: dark
+      # Avatar customization
+      avatar:
+        size: medium  # Options: small (150px), medium (200px, default), large (320px), xl (400px), xxl (500px)
+        shape: circle # Options: circle (default), square, rounded
       background:
         color: black
         image:
diff --git a/starters/blog/config/_default/hugo.yaml b/starters/blog/config/_default/hugo.yaml
index f8f1d864..2b95acd6 100644
--- a/starters/blog/config/_default/hugo.yaml
+++ b/starters/blog/config/_default/hugo.yaml
@@ -62,8 +62,9 @@ outputs:
   section: [HTML, RSS]
 imaging:
   resampleFilter: lanczos
-  quality: 95
+  quality: 90
   anchor: smart
+  hint: picture
 timeout: 600000
 taxonomies:
   tag: tags
diff --git a/starters/blog/content/_index.md b/starters/blog/content/_index.md
index a07cdc5e..73341a9c 100644
--- a/starters/blog/content/_index.md
+++ b/starters/blog/content/_index.md
@@ -12,6 +12,10 @@ sections:
         padding: [0, 0, 0, 0]
       biography:
         style: 'text-align: justify; font-size: 0.8em;'
+      # Avatar customization
+      avatar:
+        size: medium  # Options: small (150px), medium (200px, default), large (320px), xl (400px), xxl (500px)
+        shape: circle # Options: circle (default), square, rounded
   - block: collection
     content:
       filters:
diff --git a/starters/documentation/config/_default/hugo.yaml b/starters/documentation/config/_default/hugo.yaml
index 45c2dab2..96700566 100644
--- a/starters/documentation/config/_default/hugo.yaml
+++ b/starters/documentation/config/_default/hugo.yaml
@@ -73,8 +73,9 @@ outputs:
   section: [HTML, RSS]
 imaging:
   resampleFilter: lanczos
-  quality: 85
+  quality: 90
   anchor: smart
+  hint: picture
 timeout: 600000
 taxonomies:
   tag: tags
diff --git a/starters/landing-page/config/_default/hugo.yaml b/starters/landing-page/config/_default/hugo.yaml
index 700752b7..4784d873 100644
--- a/starters/landing-page/config/_default/hugo.yaml
+++ b/starters/landing-page/config/_default/hugo.yaml
@@ -68,8 +68,9 @@ outputs:
   section: [HTML, RSS]
 imaging:
   resampleFilter: lanczos
-  quality: 95
+  quality: 90
   anchor: smart
+  hint: picture
 timeout: 600000
 taxonomies:
   tag: tags
diff --git a/starters/link-in-bio/config/_default/hugo.yaml b/starters/link-in-bio/config/_default/hugo.yaml
index a5f9a4b9..4ac74ed8 100644
--- a/starters/link-in-bio/config/_default/hugo.yaml
+++ b/starters/link-in-bio/config/_default/hugo.yaml
@@ -37,8 +37,9 @@ outputs:
   section: [HTML, RSS]
 imaging:
   resampleFilter: lanczos
-  quality: 80
+  quality: 90
   anchor: smart
+  hint: picture
 timeout: 600000
 taxonomies:
   author: authors
diff --git a/starters/link-in-bio/content/_index.md b/starters/link-in-bio/content/_index.md
index 83d2b074..f26b0542 100644
--- a/starters/link-in-bio/content/_index.md
+++ b/starters/link-in-bio/content/_index.md
@@ -17,6 +17,10 @@ sections:
     design:
       biography:
         style: 'text-align: justify; font-size: 0.8em;'
+      # Avatar customization
+      avatar:
+        size: medium  # Options: small (150px), medium (200px, default), large (320px), xl (400px), xxl (500px)
+        shape: circle # Options: circle (default), square, rounded
   - block: cta-button-list
     content:
       # Need a custom icon?
diff --git a/starters/resume/config/_default/hugo.yaml b/starters/resume/config/_default/hugo.yaml
index 68693915..5e7187fe 100644
--- a/starters/resume/config/_default/hugo.yaml
+++ b/starters/resume/config/_default/hugo.yaml
@@ -37,8 +37,9 @@ outputs:
   section: [HTML, RSS]
 imaging:
   resampleFilter: lanczos
-  quality: 80
+  quality: 90
   anchor: smart
+  hint: picture
 timeout: 600000
 taxonomies:
   author: authors
diff --git a/starters/resume/content/_index.md b/starters/resume/content/_index.md
index e4c68298..506029cf 100644
--- a/starters/resume/content/_index.md
+++ b/starters/resume/content/_index.md
@@ -25,6 +25,10 @@ sections:
       biography:
         # Customize the style of your biography text
         style: 'text-align: justify; font-size: 0.8em;'
+      # Avatar customization 
+      avatar:
+        size: large     # Options: small (150px), medium (200px, default), large (320px), xl (400px), xxl (500px)
+        shape: rounded  # Options: circle (default), square, rounded
   - block: experience
     content:
       username: admin