docs(images[cls]): prevent layout shift and add non-blocking loading

why: Every <img> on the docs site lacked dimension hints, causing Cumulative Layout Shift (CLS) on page load. what: - Add content-visibility: auto on all img for off-screen decode skip - Add height: auto !important for lazy-loaded images with aspect-ratio - Add CSS height: 20px for shields.io / badge / codecov badges - Add sidebar/brand.html with width/height/decoding on logo
vcs-python · tony · Mar 14, 2026 · Mar 14, 2026 · Mar 14, 2026 · Mar 14, 2026
commit f83b0cb012216e9f7548135177aac3897b559cb5
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -187,3 +187,31 @@ samp {
 article {
   line-height: 1.6;
 }
+
+/* ── Image layout shift prevention ────────────────────────
+ * Reserve space for images before they load. Furo already
+ * sets max-width: 100%; height: auto on img. We add
+ * content-visibility and badge-specific height to prevent CLS.
+ * ────────────────────────────────────────────────────────── */
+
+img {
+  content-visibility: auto;
+}
+
+/* Docutils emits :width:/:height: as inline CSS (style="width: Xpx;
+ * height: Ypx;") rather than HTML attributes.  When Furo's
+ * max-width: 100% constrains width below the declared value,
+ * the fixed height causes distortion.  height: auto + aspect-ratio
+ * lets the browser compute the correct height from the intrinsic
+ * ratio once loaded; before load, aspect-ratio reserves space
+ * at the intended proportion — preventing both CLS and distortion. */
+article img[loading="lazy"] {
+  height: auto !important;
+}
+
+img[src*="shields.io"],
+img[src*="badge.svg"],
+img[src*="codecov.io"] {
+  height: 20px;
+  width: auto;
+}
diff --git a/docs/_templates/sidebar/brand.html b/docs/_templates/sidebar/brand.html
@@ -0,0 +1,18 @@
+<a class="sidebar-brand{% if logo %} centered{% endif %}" href="{{ pathto(master_doc) }}">
+  {%- block brand_content %}
+  {%- if logo_url %}
+  <div class="sidebar-logo-container">
+    <img class="sidebar-logo" src="{{ logo_url }}" width="200" height="200" decoding="async" alt="Logo"/>
+  </div>
+  {%- endif %}
+  {%- if theme_light_logo and theme_dark_logo %}
+  <div class="sidebar-logo-container">
+    <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" width="200" height="200" decoding="async" alt="Light Logo"/>
+    <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" width="200" height="200" decoding="async" alt="Dark Logo"/>
+  </div>
+  {%- endif %}
+  {% if not theme_sidebar_hide_name %}
+  <span class="sidebar-brand-text">{{ docstitle if docstitle else project }}</span>
+  {%- endif %}
+  {% endblock brand_content %}
+</a>