perf: improve blog and homepage image performance (lazy-loading, responsive, docs) #264

Made-with: Cursor

Author: Shivampal157

CONTRIBUTING.md

@@ -54,6 +54,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
 
 - **Quarto (`.qmd`) Posts:** Add a metadata block at the beginning of your

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">

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>

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;
+}

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">

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>

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

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>

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 }}

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">