diff --git a/_layouts/home.html b/_layouts/home.html
index 0161ad8fd3c..971d8c80c30 100644
--- a/_layouts/home.html
+++ b/_layouts/home.html
@@ -86,7 +86,37 @@
{% assign alt = post.image.alt | xml_escape | default: 'Preview Image' %}
-

+ {% if post.image.light or post.image.dark %} {% if post.image.light %}
+

+ {% endif %} {% if post.image.dark %}
+

+ {% endif %} {% else %}
+

+ {% endif %}
{% assign card_body_col = '7' %}
diff --git a/_layouts/post.html b/_layouts/post.html
index 698c86cf698..fdb5242c609 100644
--- a/_layouts/post.html
+++ b/_layouts/post.html
@@ -36,16 +36,17 @@
-
![]()
+ {% if page.image.light or page.image.dark %}
+ {% if page.image.light %}
+

+ {% endif %}
+ {% if page.image.dark %}
+

+ {% endif %}
+ {% else %}
+

+ {% endif %}
{%- if page.image.alt -%}
{{ page.image.alt }}
{%- endif -%}
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
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: