document the new feature

Author: mlange-42

guide/src/format/images/rust-logo-blk-dark.svg

@@ -117,6 +117,28 @@ Which, of course displays the image like so:
 
 ![The Rust Logo](images/rust-logo-blk.svg)
 
+## Theme-dependent images
+
+Image variants for different themes can be used via CSS classes.
+
+Here is an example for different images for light vs. dark themes:
+
+```markdown
+<img src="images/rust-logo-blk.svg" class="no-dark-themes" />
+<img src="images/rust-logo-blk-dark.svg" class="no-light-themes" />
+```
+
+Try switching the theme to see the effect below (brush icon at the top left of the page):
+
+<img src="images/rust-logo-blk.svg" class="no-dark-themes" />
+<img src="images/rust-logo-blk-dark.svg" class="no-light-themes" />
+
+To exclude an image (or any HTML element) for all dark or all light themes
+(incl. the Rust theme), use the classes `no-dark-themes` and `no-light-themes`.
+
+For even more control, elements can be hidden on an individual theme basis using the classes
+`no-light`, `no-rust`, `no-coal`, `no-navy` and `no-ayu`.
+
 ## Extensions
 
 mdBook has several extensions beyond the standard CommonMark specification.

guide/src/format/markdown.md

@@ -18,6 +18,7 @@ Here are the files you can override:
     - **_css/chrome.css_** is for UI elements.
     - **_css/general.css_** is the base styles.
     - **_css/print.css_** is the style for printer output.
+    - **_css/exclude.css_** is for [theme-dependent images](../markdown.md#theme-dependent-images).
     - **_css/variables.css_** contains variables used in other CSS files.
 - **_book.js_** is mostly used to add client side functionality, like hiding /
   un-hiding the sidebar, changing the theme, ...