Theme-dependent image variants

guide/src/format/markdown.md

@@ -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/theme/README.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, ...

src/book/init.rs

@@ -143,6 +143,9 @@ impl BookBuilder {
         let mut variables_css = File::create(cssdir.join("variables.css"))?;
         variables_css.write_all(theme::VARIABLES_CSS)?;
 
+        let mut excludes_css = File::create(cssdir.join("exclude.css"))?;
+        excludes_css.write_all(theme::EXCLUDES_CSS)?;
+
         let mut favicon = File::create(themedir.join("favicon.png"))?;
         favicon.write_all(theme::FAVICON_PNG)?;
 

src/renderer/html_handlebars/hbs_renderer.rs

@@ -229,6 +229,7 @@ impl HtmlHandlebars {
             write_file(destination, "css/print.css", &theme.print_css)?;
         }
         write_file(destination, "css/variables.css", &theme.variables_css)?;
+        write_file(destination, "css/exclude.css", &theme.excludes_css)?;
         if let Some(contents) = &theme.favicon_png {
             write_file(destination, "favicon.png", contents)?;
         }

src/theme/css/exclude.css

@@ -0,0 +1,18 @@
+.light .no-light,
+.rust .no-rust,
+.navy .no-navy,
+.ayu .no-ayu,
+.coal .no-coal {
+    display: none;
+}
+
+.light .no-light-themes,
+.rust .no-light-themes {
+    display: none;
+}
+
+.navy .no-dark-themes,
+.ayu .no-dark-themes,
+.coal .no-dark-themes {
+    display: none;
+}

src/theme/index.hbs

@@ -28,6 +28,7 @@
         <link rel="stylesheet" href="{{ path_to_root }}css/variables.css">
         <link rel="stylesheet" href="{{ path_to_root }}css/general.css">
         <link rel="stylesheet" href="{{ path_to_root }}css/chrome.css">
+        <link rel="stylesheet" href="{{ path_to_root }}css/exclude.css">
         {{#if print_enable}}
         <link rel="stylesheet" href="{{ path_to_root }}css/print.css" media="print">
         {{/if}}

src/theme/mod.rs

@@ -21,6 +21,7 @@ pub static CHROME_CSS: &[u8] = include_bytes!("css/chrome.css");
 pub static GENERAL_CSS: &[u8] = include_bytes!("css/general.css");
 pub static PRINT_CSS: &[u8] = include_bytes!("css/print.css");
 pub static VARIABLES_CSS: &[u8] = include_bytes!("css/variables.css");
+pub static EXCLUDES_CSS: &[u8] = include_bytes!("css/exclude.css");
 pub static FAVICON_PNG: &[u8] = include_bytes!("favicon.png");
 pub static FAVICON_SVG: &[u8] = include_bytes!("favicon.svg");
 pub static JS: &[u8] = include_bytes!("book.js");
@@ -54,6 +55,7 @@ pub struct Theme {
     pub general_css: Vec<u8>,
     pub print_css: Vec<u8>,
     pub variables_css: Vec<u8>,
+    pub excludes_css: Vec<u8>,
     pub favicon_png: Option<Vec<u8>>,
     pub favicon_svg: Option<Vec<u8>>,
     pub js: Vec<u8>,
@@ -91,6 +93,7 @@ impl Theme {
                     theme_dir.join("css/variables.css"),
                     &mut theme.variables_css,
                 ),
+                (theme_dir.join("css/exclude.css"), &mut theme.excludes_css),
                 (theme_dir.join("highlight.js"), &mut theme.highlight_js),
                 (theme_dir.join("clipboard.min.js"), &mut theme.clipboard_js),
                 (theme_dir.join("highlight.css"), &mut theme.highlight_css),
@@ -153,6 +156,7 @@ impl Default for Theme {
             general_css: GENERAL_CSS.to_owned(),
             print_css: PRINT_CSS.to_owned(),
             variables_css: VARIABLES_CSS.to_owned(),
+            excludes_css: EXCLUDES_CSS.to_owned(),
             favicon_png: Some(FAVICON_PNG.to_owned()),
             favicon_svg: Some(FAVICON_SVG.to_owned()),
             js: JS.to_owned(),
@@ -213,6 +217,7 @@ mod tests {
             "css/general.css",
             "css/print.css",
             "css/variables.css",
+            "css/exclude.css",
             "book.js",
             "highlight.js",
             "tomorrow-night.css",
@@ -240,6 +245,7 @@ mod tests {
             general_css: Vec::new(),
             print_css: Vec::new(),
             variables_css: Vec::new(),
+            excludes_css: Vec::new(),
             favicon_png: Some(Vec::new()),
             favicon_svg: Some(Vec::new()),
             js: Vec::new(),

tests/init.rs

@@ -116,6 +116,7 @@ fn copy_theme() {
     let expected = vec![
         "book.js",
         "css/chrome.css",
+        "css/exclude.css",
         "css/general.css",
         "css/print.css",
         "css/variables.css",