Add a logo to the navigation bar of the HTML rendered book

crates/mdbook-core/src/config.rs

@@ -45,11 +45,11 @@
 
 use crate::static_regex;
 use crate::utils::{TomlExt, fs, log_backtrace};
-use anyhow::{Context, Error, Result, bail};
+use anyhow::{Context, Error, Result, anyhow, bail};
 use serde::{Deserialize, Serialize};
 use std::collections::{BTreeMap, HashMap};
 use std::env;
-use std::path::{Path, PathBuf};
+use std::path::{Component, Path, PathBuf};
 use std::str::FromStr;
 use toml::Value;
 use toml::value::Table;
@@ -303,6 +303,31 @@ impl Config {
 
         Ok(())
     }
+
+    /// The config can load properly with valid, but wrong values, for instance wrong paths.
+    /// This is the place to check for such config variables.
+    pub fn check<P: Into<PathBuf>>(&self, book_root: P) -> Result<()> {
+        if let Some(logo_path) = self.book.get_logo_absolute_path(book_root) {
+            // Forbid absolute paths and parent directory references in the config file
+            if let Some(logo_path) = &self.book.logo {
+                if logo_path.is_absolute()
+                    || logo_path.components().any(|c| c == Component::ParentDir)
+                {
+                    return Result::Err(anyhow!(
+                        "invalid value for `logo`: should live under `{}/`",
+                        self.book.src.to_string_lossy()
+                    ));
+                }
+            }
+            if !logo_path.exists() {
+                return Result::Err(anyhow!(
+                    "invalid value for `logo`: {} does not exist",
+                    logo_path.to_str().unwrap_or(&logo_path.to_string_lossy()),
+                ));
+            }
+        }
+        Result::Ok(())
+    }
 }
 
 fn parse_env(key: &str) -> Option<String> {
@@ -330,6 +355,9 @@ pub struct BookConfig {
     /// The direction of text in the book: Left-to-right (LTR) or Right-to-left (RTL).
     /// When not specified, the text direction is derived from [`BookConfig::language`].
     pub text_direction: Option<TextDirection>,
+    /// A logo to be displayed on top of the navigation bar. The path is relative to the source
+    /// path
+    pub logo: Option<PathBuf>,
 }
 
 /// Helper for serde serialization.
@@ -346,6 +374,7 @@ impl Default for BookConfig {
             src: PathBuf::from("src"),
             language: Some(String::from("en")),
             text_direction: None,
+            logo: None,
         }
     }
 }
@@ -360,6 +389,19 @@ impl BookConfig {
             TextDirection::from_lang_code(self.language.as_deref().unwrap_or_default())
         }
     }
+
+    /// Compute the absolute path of the book's logo, if provided, and canonicalize it
+    pub fn get_logo_absolute_path<P: Into<PathBuf>>(&self, book_root: P) -> Option<PathBuf> {
+        if let Some(logo_cfg) = self.logo.clone() {
+            Some(if logo_cfg.is_absolute() {
+                logo_cfg
+            } else {
+                book_root.into().join(&self.src).join(logo_cfg)
+            })
+        } else {
+            None
+        }
+    }
 }
 
 /// Text direction to use for HTML output
@@ -742,6 +784,7 @@ mod tests {
         description = "A completely useless book"
         src = "source"
         language = "ja"
+        logo = "images/logo.svg"
 
         [build]
         build-dir = "outputs"
@@ -779,6 +822,7 @@ mod tests {
             src: PathBuf::from("source"),
             language: Some(String::from("ja")),
             text_direction: None,
+            logo: Some(PathBuf::from("images/logo.svg")),
         };
         let build_should_be = BuildConfig {
             build_dir: PathBuf::from("outputs"),

crates/mdbook-driver/src/mdbook.rs

@@ -57,6 +57,7 @@ impl MDBook {
         };
 
         config.update_from_env()?;
+        config.check(book_root.clone())?;
 
         if tracing::enabled!(tracing::Level::TRACE) {
             for line in format!("Config: {config:#?}").lines() {

crates/mdbook-html/front-end/css/chrome.css

@@ -498,6 +498,25 @@ html:not(.sidebar-resizing) .sidebar {
     right: 0;
     padding: 10px 10px;
 }
+.sidebar .sidebar-scrollbox .sidebar-book-logo {
+    align-items: center;
+    column-gap: 20px;
+    display: flex;
+    justify-content: center;
+    margin: 20px 0;
+}
+.sidebar .sidebar-scrollbox .sidebar-book-logo img {
+    display: block;
+    max-height: 8rem;
+    width: 20%;
+}
+.sidebar .sidebar-scrollbox .sidebar-book-logo h2 {
+    margin: 0;
+    width: 70%;
+    overflow-wrap: anywhere;
+    text-wrap: balance;
+}
+
 .sidebar .sidebar-resize-handle {
     position: absolute;
     cursor: col-resize;

crates/mdbook-html/front-end/templates/toc.js.hbs

@@ -8,7 +8,14 @@ class MDBookSidebarScrollbox extends HTMLElement {
         super();
     }
     connectedCallback() {
+{{#if book_logo }}
+        this.innerHTML =
+            '<div id="sidebar-book-logo" class="sidebar-book-logo">' +
+            '<img src="' + path_to_root + '{{ book_logo }}" alt="{{ book_title }}" />' +
+            '<h2 class="sidebar-logo-title">{{ book_title }}</h2></div>{{#toc}}{{/toc}}';
+{{else}}
         this.innerHTML = '{{#toc}}{{/toc}}';
+{{/if}}
         // Set the current, active page, and reveal it if it's hidden
         let current_page = document.location.href.toString().split('#')[0].split('?')[0];
         if (current_page.endsWith('/')) {

crates/mdbook-html/src/html_handlebars/hbs_renderer.rs

@@ -478,6 +478,10 @@ fn make_data(
         "description".to_owned(),
         json!(config.book.description.clone().unwrap_or_default()),
     );
+    data.insert(
+        "book_logo".to_owned(),
+        json!(config.book.logo.clone().unwrap_or_default()),
+    );
     if theme.favicon_png.is_some() {
         data.insert("favicon_png".to_owned(), json!("favicon.png"));
     }

guide/book.toml

@@ -3,6 +3,7 @@ title = "mdBook Documentation"
 description = "Create book from markdown files. Like Gitbook but implemented in Rust"
 authors = ["Mathieu David", "Michael-F-Bryan"]
 language = "en"
+logo = "images/logo.svg"
 
 [rust]
 edition = "2018"

guide/src/format/configuration/general.md

@@ -49,8 +49,10 @@ This is general information about your book.
   This is also used to derive the direction of text (RTL, LTR) within the book.
 - **text-direction**: The direction of text in the book: Left-to-right (LTR) or Right-to-left (RTL). Possible values: `ltr`, `rtl`.
   When not specified, the text direction is derived from the book's `language` attribute.
+- **logo:** Path to a logo to displayed at the top of the navigation bar, relative to `<book_root>/<src>/`.
 
 **book.toml**
+
 ```toml
 [book]
 title = "Example book"
@@ -59,6 +61,7 @@ description = "The example book covers examples."
 src = "my-src"  # the source files will be found in `root/my-src` instead of `root/src`
 language = "en"
 text-direction = "ltr"
+logo = "static/logo.svg"  # logo lives at `root/my-src/static/logo.svg`
 ```
 
 ### Rust options

guide/src/images/logo.svg

@@ -0,0 +1 @@
+../../../crates/mdbook-html/front-end/images/favicon.svg

tests/gui/books/sidebar-logo-large/book.toml

@@ -0,0 +1,3 @@
+[book]
+title = "Large logo"
+logo = "logo.svg"

tests/gui/books/sidebar-logo-large/src/SUMMARY.md

@@ -0,0 +1 @@
+- [c1](c1.md)

tests/gui/books/sidebar-logo-large/src/c1.md

@@ -0,0 +1 @@
+# c1

tests/gui/books/sidebar-logo-tall/book.toml

@@ -0,0 +1,3 @@
+[book]
+title = "Tall logo"
+logo = "logo.svg"

tests/gui/books/sidebar-logo-tall/src/SUMMARY.md

@@ -0,0 +1 @@
+- [c1](c1.md)

tests/gui/books/sidebar-logo-tall/src/c1.md

@@ -0,0 +1 @@
+# c1

tests/gui/books/sidebar-logo/book.toml

@@ -0,0 +1,4 @@
+[book]
+title = "sidebar-logo test"
+language = "en"
+logo = "logo.svg"

tests/gui/books/sidebar-logo/src/SUMMARY.md

@@ -0,0 +1,6 @@
+# Summary
+
+- [Chapter 1](./chapter_1.md)
+- [Chapter 2](./chapter_2.md)
+- [Nested](./nested/chapter_nested.md)
+- [Deeper](./nested/again/chapter_nested.md)

tests/gui/books/sidebar-logo/src/chapter_1.md

@@ -0,0 +1,3 @@
+# Chapter 1
+
+This is the first chapter to test logo display at root level.

tests/gui/books/sidebar-logo/src/chapter_2.md

@@ -0,0 +1,3 @@
+# Chapter 2
+
+This is the second chapter.

tests/gui/books/sidebar-logo/src/nested/again/chapter_nested.md

@@ -0,0 +1,3 @@
+# Deeper Chapter
+
+This is a nested chapter to test logo display at different nesting levels.

tests/gui/books/sidebar-logo/src/nested/chapter_nested.md

@@ -0,0 +1,3 @@
+# Nested Chapter
+
+This is a nested chapter to test logo display at different nesting levels.

tests/gui/sidebar-logo.goml

@@ -0,0 +1,87 @@
+// This GUI test checks that the logo is displayed when configured
+// Test cases:
+// - test if the logo is displayed when provided
+// - test it is displayed above the toc
+// - test if works in nested files (level 0, 1 and n > 1)
+// - large pictures are properly displayed
+
+define-function: (
+    "load",
+    [path],
+    block {
+    go-to: |DOC_PATH| + |path|
+    set-window-size: (1100, 600)
+    reload:
+    // Wait for the TOC to be populated by JavaScript
+    wait-for: "mdbook-sidebar-scrollbox"
+    wait-for: "ol.chapter"
+    wait-for: "#sidebar-book-logo"
+    },
+)
+
+define-function: (
+    "assert-logo",
+    [],
+    block {
+        assert-css: ("#sidebar-book-logo", {"display": "flex"})
+        assert-css: ("#sidebar-book-logo img", {"display": "block"})
+    },
+)
+
+define-function: (
+    "assert-logo-src",
+    [prefix],
+    block {
+        assert-attribute: (".sidebar-book-logo img", {"src": |prefix| + "logo.svg"})
+        assert-find-text-false: "sidebar-logo test logo"
+    },
+)
+
+define-function: (
+    "assert-logo-position",
+    [],
+    block {
+        store-position: ("#sidebar-book-logo img", {"y": logo_y})
+        store-position: ("ol.chapter", {"y": chapter_y})
+        assert: |logo_y| < |chapter_y|
+    },
+)
+
+call-function: ("load", {"path": "sidebar-logo/index.html"})
+
+// The sidebar-book-logo should exist when logo is provided
+call-function: ("assert-logo", {})
+
+// Logo image should have the correct src path and loaded
+call-function: ("assert-logo-src", {"prefix": ""})
+
+// Logo should be above the TOC
+call-function: ("assert-logo-position", {})
+
+// Test on chapter_2, nested, and deeper
+click: ".chapter a[href='chapter_2.html']"
+wait-for-text: (".header", "Chapter 2")
+call-function: ("assert-logo", {})
+call-function: ("assert-logo-src", {"prefix": ""})
+call-function: ("assert-logo-position", {})
+
+click: ".chapter a[href='nested/chapter_nested.html']"
+wait-for-text: (".header", "Nested Chapter")
+call-function: ("assert-logo", {})
+call-function: ("assert-logo-src", {"prefix": "../"})
+call-function: ("assert-logo-position", {})
+
+click: ".chapter a[href='../nested/again/chapter_nested.html']"
+wait-for-text: (".header", "Deeper Chapter")
+call-function: ("assert-logo", {})
+call-function: ("assert-logo-src", {"prefix": "../../"})
+call-function: ("assert-logo-position", {})
+
+// Large images checks
+call-function: ("load", {"path": "sidebar-logo-large/index.html"})
+store-property : (".sidebar-book-logo img", {"width": logo_width})
+assert: |logo_width| <= 200
+
+call-function: ("load", {"path": "sidebar-logo-tall/index.html"})
+store-property : (".sidebar-book-logo img", {"height": logo_height})
+assert: |logo_height| <= 200

tests/gui/sidebar.goml

@@ -67,3 +67,6 @@ assert-local-storage: {|sidebar_storage_value|: |sidebar_storage_displayed_value
 // But the sidebar should be hidden anyway.
 assert-css: ("#mdbook-sidebar", {"display": "none"})
 assert-position: ("#mdbook-page-wrapper", {"x": 0})
+
+// The logo should not be displayed in the sidebar.
+assert-false: "#sidebar-book-logo"

tests/testsuite/config.rs

@@ -176,7 +176,7 @@ ERROR Invalid configuration file
   |
 3 | foo = 123
   | ^^^
-unknown field `foo`, expected one of `title`, `authors`, `description`, `src`, `language`, `text-direction`
+unknown field `foo`, expected one of `title`, `authors`, `description`, `src`, `language`, `text-direction`, `logo`
 
 
 "#]]);
@@ -232,7 +232,7 @@ fn env_invalid_value() {
                 .expect_failure()
                 .expect_stdout(str![[""]])
                 .expect_stderr(str![[r#"
-ERROR unknown field `titlez`, expected one of `title`, `authors`, `description`, `src`, `language`, `text-direction`
+ERROR unknown field `titlez`, expected one of `title`, `authors`, `description`, `src`, `language`, `text-direction`, `logo`
 
 
 "#]]);

tests/testsuite/main.rs

@@ -20,6 +20,7 @@ mod renderer;
 mod rendering;
 #[cfg(feature = "search")]
 mod search;
+mod sidebar_logo;
 mod test;
 mod theme;
 mod toc;

tests/testsuite/preprocessor.rs

@@ -362,6 +362,7 @@ fn extension_compatibility() {
           "authors": [],
           "description": null,
           "language": "en",
+          "logo": null,
           "text-direction": null,
           "title": "extension_compatibility"
         },

tests/testsuite/renderer.rs

@@ -188,6 +188,7 @@ fn backends_receive_render_context_via_stdin() {
       "authors": [],
       "description": null,
       "language": "en",
+      "logo": null,
       "text-direction": null,
       "title": null
     },

tests/testsuite/sidebar/logo/absolute_unix/book.toml

@@ -0,0 +1,5 @@
+[book]
+title = "outside"
+authors = ["Chocorean"]
+language = "en"
+logo = "/absolute/path/logo.svg"

tests/testsuite/sidebar/logo/absolute_unix/src/SUMMARY.md

@@ -0,0 +1,3 @@
+# Summary
+
+- [Chapter 1](./chapter_1.md)

tests/testsuite/sidebar/logo/absolute_unix/src/chapter_1.md

@@ -0,0 +1 @@
+# Chapter 1