From a51d8aabbfb0f88fd7ad682183d4105a177fd8fc Mon Sep 17 00:00:00 2001
From: Shivampal157 <shivampal60076@gmail.com>
Date: Sun, 15 Mar 2026 02:03:20 +0530
Subject: [PATCH] perf: improve blog and homepage image performance
 (lazy-loading, responsive, docs) #264

Made-with: Cursor
---
 CONTRIBUTING.md      | 12 ++++++++++++
 theme/base.html      |  2 +-
 theme/blog-post.html |  2 +-
 theme/css/blog.css   | 11 +++++++++++
 theme/events.html    |  4 ++--
 theme/home.html      |  2 +-
 theme/js/theme.js    |  6 ++++++
 theme/partners.html  |  2 +-
 theme/projects.html  |  2 ++
 theme/team.html      |  2 +-
 10 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a0dbe1abf..16861ec62 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -56,6 +56,18 @@ dependencies and activate it.
    - Place a header image (either `header.png` or `header.jpg`) in your blog
      post folder. Make sure the image is under a free license.
 
+### Authoring images (performance and accessibility)
+
+- **Alt text:** Always add descriptive `alt` text for images (e.g. in Markdown:
+  `![Description of the image](image.png)`). This helps accessibility and SEO.
+- **Dimensions:** Prefer images with reasonable dimensions (e.g. 1200px wide for
+  in-content screenshots). The theme applies responsive sizing and lazy-loading
+  to blog content images; very large originals will still be downscaled by the
+  browser but use more bandwidth.
+- **Format:** PNG or JPEG is fine. For very large images, consider providing
+  WebP versions where the build or CMS supports it; the theme can use
+  `<picture>` / `srcset` for fallbacks.
+
 ### Metadata and Formatting
 
 - **Markdown Posts:** Add a metadata block at the beginning of your `index.md`
diff --git a/theme/base.html b/theme/base.html
index 22ee2ba23..c70aaf3a6 100644
--- a/theme/base.html
+++ b/theme/base.html
@@ -498,7 +498,7 @@ <h2 class="accordion-header" id="h-{{ pid }}">
           </div>
           <div class="d-flex align-items-center gap-3">
             <a rel="license" href="https://creativecommons.org/licenses/by-sa/4.0/">
-              <img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png">
+              <img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" width="88" height="31" loading="lazy" decoding="async">
             </a>
             <div class="color_mode">
               <input type="checkbox" class="color_choice" id="mode" aria-label="Toggle color mode">
diff --git a/theme/blog-post.html b/theme/blog-post.html
index febdcaa9e..b2a4883b6 100644
--- a/theme/blog-post.html
+++ b/theme/blog-post.html
@@ -79,7 +79,7 @@ <h1 class="post-title">
         <article>
           <a href="{{ sub_nav_item.url|url }}" class="image">
             <img src="https://picsum.photos/id/{{ loop.index }}/400/200"
-                 alt="{{ sub_nav_item.title }}" />
+                 alt="{{ sub_nav_item.title }}" loading="lazy" decoding="async" width="400" height="200" />
           </a>
           <h3>{{ sub_nav_item.title }}</h3>
           <p>{{ sub_nav_item.summary }}</p>
diff --git a/theme/css/blog.css b/theme/css/blog.css
index 210b3f071..2cccce0d3 100644
--- a/theme/css/blog.css
+++ b/theme/css/blog.css
@@ -221,3 +221,14 @@
 
 /* Safety: never allow gigantic SVGs inside blog content */
 .blog-article .post_body svg.icon { width: 1em; height: 1em; }
+
+/* Responsive images in blog content (LCP / defer offscreen images) */
+.blog-article .post_body img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+}
+.blog-article .post_body img:not([width]):not([height]) {
+  /* Reserve space to reduce CLS when dimensions unknown */
+  min-height: 1px;
+}
diff --git a/theme/events.html b/theme/events.html
index 8b1aefb85..07bca23fa 100644
--- a/theme/events.html
+++ b/theme/events.html
@@ -14,7 +14,7 @@ <h2>Upcoming Events</h2>
       <div class="row {{ colors[loop.index % 2] }}">
         <div class="col-4 text-center">
           <a href="{{ event.url }}">
-            <img src="{{ event.thumbnail }}" />
+            <img src="{{ event.thumbnail }}" alt="{{ event.name }}" loading="lazy" decoding="async" />
           </a>
         </div>
         <div class="col-8">
@@ -47,7 +47,7 @@ <h2>Past Events</h2>
       <div class="row {{ colors[loop.index % 2] }}">
         <div class="col-4 text-center">
           <a href="{{ event.url }}">
-            <img src="{{ event.thumbnail }}" />
+            <img src="{{ event.thumbnail }}" alt="{{ event.name }}" loading="lazy" decoding="async" />
           </a>
         </div>
         <div class="col-8">
diff --git a/theme/home.html b/theme/home.html
index d17121876..3361af01e 100644
--- a/theme/home.html
+++ b/theme/home.html
@@ -116,7 +116,7 @@ <h2 class="section-title">Our Partners</h2>
       {% for partner in page.meta["partners"] %}
       <li class="logo-item">
         <a href="{{ partner.url }}" target="_blank" rel="noopener">
-          <img src="{{ partner.logo }}" alt="{{ partner.name }}">
+          <img src="{{ partner.logo }}" alt="{{ partner.name }}" loading="lazy" decoding="async">
           <span class="logo-caption">{{ partner.name }}</span>
         </a>
       </li>
diff --git a/theme/js/theme.js b/theme/js/theme.js
index ea3fa4d5e..b47d79bfc 100644
--- a/theme/js/theme.js
+++ b/theme/js/theme.js
@@ -84,6 +84,12 @@
     document.querySelectorAll('.dropdown-menu.mega').forEach(menu => {
       menu.addEventListener('click', (e) => e.stopPropagation());
     });
+
+    /* 7) Lazy-load images in blog content (markdown-rendered imgs don't have loading attr) */
+    document.querySelectorAll('.post_body img:not([loading])').forEach(function (img) {
+      img.setAttribute('loading', 'lazy');
+      img.setAttribute('decoding', 'async');
+    });
   });
 
   // Optional public API
diff --git a/theme/partners.html b/theme/partners.html
index 52dcee015..7aa502a0a 100644
--- a/theme/partners.html
+++ b/theme/partners.html
@@ -18,7 +18,7 @@
         <div class="logo-wrap p-4">
           {% if logo %}
             <a href="{{ site or '#' }}" class="d-inline-flex" target="_blank" rel="noopener">
-              <img src="{{ logo }}" alt="{{ partner.name }}" />
+              <img src="{{ logo }}" alt="{{ partner.name }}" loading="lazy" decoding="async" />
             </a>
           {% endif %}
         </div>
diff --git a/theme/projects.html b/theme/projects.html
index a9ea636fe..6075f8146 100644
--- a/theme/projects.html
+++ b/theme/projects.html
@@ -25,11 +25,13 @@ <h2>
               <img
                 alt="Static Badge"
                 src="https://img.shields.io/badge/project-incubated-333333?style=for-the-badge&label=project&labelColor=FFAA00&color=888888"
+                loading="lazy" decoding="async"
               />
               {% elif project.type == "affiliated" %}
               <img
                 alt="Static Badge"
                 src="https://img.shields.io/badge/project-affiliated-333333?style=for-the-badge&label=project&labelColor=0E91C3&color=888888"
+                loading="lazy" decoding="async"
               />
               {% endif %}
               {{ project.name }}
diff --git a/theme/team.html b/theme/team.html
index 2bd456b92..e51af3371 100644
--- a/theme/team.html
+++ b/theme/team.html
@@ -25,7 +25,7 @@ <h2 class="mb-3">{{ group.name }}</h2>
         <div class="col">
           <div class="card h-100">
             {% if member.image_url %}
-              <img src="{{ member.image_url }}" class="card-img-top" alt="{{ member.name }}">
+              <img src="{{ member.image_url }}" class="card-img-top" alt="{{ member.name }}" loading="lazy" decoding="async" width="400" height="400">
             {% endif %}
 
             <div class="card-body d-flex flex-column">