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

Author: some-natalie

_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' %}

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

_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: