feat: Add dark and light variants for images

.changeset/empty-beds-heal.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Make light and dark image variants

docs/src/content/docs/guides/authoring-content.mdx

@@ -63,6 +63,18 @@ Relative image paths are also supported for images stored locally in your projec
 ![A rocketship in space](../../assets/images/rocket.svg)
 ```
 
+### Light and dark variants
+
+If you want to show different images for light and dark color schemes, you can append a `#only-light` or `#only-dark` hash fragment to the image URL:
+
+```md
+![Image for the light theme](../../assets/light-logo.svg#only-light)
+![Image for the dark theme](../../assets/dark-logo.svg#only-dark)
+```
+
+![Image for the light theme](https://github.com/user-attachments/assets/5ff75483-d761-4dbd-b3a0-c7823b137ec5#only-light)
+![Image for the dark theme](https://github.com/user-attachments/assets/ab396486-d6a3-41ac-85ff-a961f319fbca#only-dark)
+
 ## Headings
 
 You can structure content using a heading. Headings in Markdown are indicated by a number of `#` at the start of the line.

packages/starlight/style/util.css

@@ -47,6 +47,12 @@
 [data-theme='dark'] .dark\:sl-hidden {
 	display: none;
 }
+[data-theme='light'] img[src$="#only-dark"] {
+	display: none;
+}
+[data-theme='dark'] img[src$="#only-light"] {
+	display: none;
+}
 
 /*
 Flip an element around the y-axis when in an RTL context.