From fff86d9e9cda9d0ad16aa229d4bf91c1d41ddcc0 Mon Sep 17 00:00:00 2001
From: Natalie Somersall <natalie.somersall@gmail.com>
Date: Fri, 24 Oct 2025 20:26:00 +0000
Subject: [PATCH 1/2] feat(images): change preview image on post and home page
 based on light/dark mode, scaling

This PR adds the ability to change the image seen by the user for the post preview on the home page and on the page if set in the YAML front matter.

Closes Post image and homepage card color change by theme change
Fixes #2554
---
 _layouts/home.html                    | 32 +++++++++++++++++++++++-
 _layouts/post.html                    | 19 ++++++++-------
 _posts/2019-08-08-write-a-new-post.md | 35 +++++++++++++++++++++++++++
 3 files changed, 76 insertions(+), 10 deletions(-)

diff --git a/_layouts/home.html b/_layouts/home.html
index cb9ab244d48..3438f26bf27 100644
--- a/_layouts/home.html
+++ b/_layouts/home.html
@@ -67,7 +67,37 @@
           {% endif %}
 
           <div class="col-md-5">
-            <img src="{{ src }}" alt="{{ alt }}" {{ lqip }}>
+            {% if post.image.light or post.image.dark %} {% if post.image.light %}
+            <img
+              src="{{ post.image.light }}"
+              alt="{{ alt }}"
+              class="light preview-image"
+              style="{% if post.image.max_height %}max-height: {{ post.image.max_height }};{% else %}max-height: 200px;{% endif %} {% if post.image.object_fit %}object-fit: {{ post.image.object_fit }};{% else %}object-fit: cover;{% endif %} width: 100%; border-radius: 8px;"
+              {{
+              lqip
+              }}
+            />
+            {% endif %} {% if post.image.dark %}
+            <img
+              src="{{ post.image.dark }}"
+              alt="{{ alt }}"
+              class="dark preview-image"
+              style="{% if post.image.max_height %}max-height: {{ post.image.max_height }};{% else %}max-height: 200px;{% endif %} {% if post.image.object_fit %}object-fit: {{ post.image.object_fit }};{% else %}object-fit: cover;{% endif %} width: 100%; border-radius: 8px;"
+              {{
+              lqip
+              }}
+            />
+            {% endif %} {% else %}
+            <img
+              src="{{ post.image.path | default: post.image }}"
+              alt="{{ alt }}"
+              class="preview-image"
+              style="{% if post.image.max_height %}max-height: {{ post.image.max_height }};{% else %}max-height: 200px;{% endif %} {% if post.image.object_fit %}object-fit: {{ post.image.object_fit }};{% else %}object-fit: cover;{% endif %} width: 100%; border-radius: 8px;"
+              {{
+              lqip
+              }}
+            />
+            {% endif %}
           </div>
 
           {% assign card_body_col = '7' %}
diff --git a/_layouts/post.html b/_layouts/post.html
index c8c21ef7986..23b491646ec 100644
--- a/_layouts/post.html
+++ b/_layouts/post.html
@@ -37,16 +37,17 @@ <h1 data-toc-skip>{{ page.title }}</h1>
       {% endif %}
 
       {% if page.image %}
-        {% capture src %}src="{{ page.image.path | default: page.image }}"{% endcapture %}
-        {% capture class %}class="preview-img{% if page.image.no_bg %}{{ ' no-bg' }}{% endif %}"{% endcapture %}
-        {% capture alt %}alt="{{ page.image.alt | xml_escape | default: "Preview Image" }}"{% endcapture %}
-
-        {% if page.image.lqip %}
-          {%- capture lqip -%}lqip="{{ page.image.lqip }}"{%- endcapture -%}
-        {% endif %}
-
         <div class="mt-3 mb-3">
-          <img {{ src }} {{ class }} {{ alt }} w="1200" h="630" {{ lqip }}>
+          {% if page.image.light or page.image.dark %}
+            {% if page.image.light %}
+              <img src="{{ page.image.light }}" class="preview-img light" alt="{{ page.image.alt | xml_escape | default: "Preview Image" }}" w="1200" h="630" style="{% if page.image.max_height %}max-height: {{ page.image.max_height }};{% endif %} {% if page.image.object_fit %}object-fit: {{ page.image.object_fit }};{% else %}object-fit: cover;{% endif %} background-color: white; padding: 10px; border-radius: 8px; width: 100%;"{% if page.image.lqip %} lqip="{{ page.image.lqip }}"{% endif %}>
+            {% endif %}
+            {% if page.image.dark %}
+              <img src="{{ page.image.dark }}" class="preview-img dark" alt="{{ page.image.alt | xml_escape | default: "Preview Image" }}" w="1200" h="630" style="{% if page.image.max_height %}max-height: {{ page.image.max_height }};{% endif %} {% if page.image.object_fit %}object-fit: {{ page.image.object_fit }};{% else %}object-fit: cover;{% endif %} background-color: #1b1b1e; padding: 10px; border-radius: 8px; width: 100%;"{% if page.image.lqip %} lqip="{{ page.image.lqip }}"{% endif %}>
+            {% endif %}
+          {% else %}
+            <img src="{{ page.image.path | default: page.image }}" class="preview-img" alt="{{ page.image.alt | xml_escape | default: "Preview Image" }}" w="1200" h="630" style="{% if page.image.max_height %}max-height: {{ page.image.max_height }};{% endif %} {% if page.image.object_fit %}object-fit: {{ page.image.object_fit }};{% else %}object-fit: cover;{% endif %} padding: 10px; border-radius: 8px; width: 100%;"{% if page.image.lqip %} lqip="{{ page.image.lqip }}"{% endif %}>
+          {% endif %}
           {%- if page.image.alt -%}
             <figcaption class="text-center pt-2 pb-2">{{ page.image.alt }}</figcaption>
           {%- endif -%}
diff --git a/_posts/2019-08-08-write-a-new-post.md b/_posts/2019-08-08-write-a-new-post.md
index f048f013c4a..01e055d8230 100644
--- a/_posts/2019-08-08-write-a-new-post.md
+++ b/_posts/2019-08-08-write-a-new-post.md
@@ -256,6 +256,41 @@ For normal images:
 ```
 {: .nolineno }
 
+#### Preview light/dark images
+
+It is also possible to have the image differ based on if the user is seeing your site in light mode or dark mode:
+
+```yaml
+---
+image:
+  light: /path/to/image-light.png
+  dark: /path/to/image-dark.png
+  alt: this is some alt text
+---
+```
+
+#### Preview scaling
+
+For the home page, the height of the image preview and how it scales to fit can be set.
+
+```yaml
+---
+image: 
+  path: /path/to/image.jpeg
+  alt: this is some alt text
+  object_fit: contain
+  max_height: 200px # default
+---
+```
+
+Available object-fit values:
+
+- **`cover`** (default) - Scales to fill container, may crop edges to maintain aspect ratio
+- **`contain`** - Scales to fit entirely within container, may leave empty space
+- **`fill`** - Stretches to fill container exactly (may distort aspect ratio)
+- **`scale-down`** - Acts like `contain` but never scales up beyond original size
+- **`none`** - Image is not resized
+
 ### Social Media Platforms
 
 You can embed video/audio from social media platforms with the following syntax:

From 248d70cd09dbf645b6ab9b09e008c8752cadd7fc Mon Sep 17 00:00:00 2001
From: Natalie Somersall <natalie.somersall@gmail.com>
Date: Thu, 30 Oct 2025 18:38:12 -0600
Subject: [PATCH 2/2] feat(images): create social image plugin

Signed-off-by: Natalie Somersall <natalie.somersall@gmail.com>
---
 _plugins/default-social-image.rb | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
 create mode 100644 _plugins/default-social-image.rb

diff --git a/_plugins/default-social-image.rb b/_plugins/default-social-image.rb
new file mode 100644
index 00000000000..fe5830e8498
--- /dev/null
+++ b/_plugins/default-social-image.rb
@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+Jekyll::Hooks.register :pages, :pre_render do |page|
+  set_default_social_image(page)
+end
+
+Jekyll::Hooks.register :posts, :pre_render do |post|
+  set_default_social_image(post)
+end
+
+Jekyll::Hooks.register :documents, :pre_render do |document|
+  set_default_social_image(document)
+end
+
+def set_default_social_image(page_or_post)
+  return unless page_or_post.data['image'].is_a?(Hash)
+
+  image_data = page_or_post.data['image']
+
+  # If we have light or dark variants but no main image set for social sharing
+  if (image_data['light'] || image_data['dark']) && !image_data['path']
+    # Prefer light image for social sharing, fallback to dark if light doesn't exist
+    social_image = image_data['light'] || image_data['dark']
+
+    # Set the path for jekyll-seo-tag to use
+    page_or_post.data['image']['path'] = social_image
+  end
+end