Merge pull request #3037 from cobyfrombrooklyn-bot/fix-issue-3023

Fix #3023: Improve error message for invalid Font Awesome icons

crates/mdbook-html/src/html_handlebars/helpers/fontawesome.rs

@@ -43,10 +43,14 @@ pub(crate) fn fa_helper(
     } else {
         out.write("<span class=fa-svg>")?;
     }
-    out.write(
-        fa::svg(type_, name)
-            .map_err(|_| RenderErrorReason::Other(format!("Missing font {}", name)))?,
-    )?;
+    out.write(fa::svg(type_, name).map_err(|_| {
+        let valid_types = "fas (solid), fab (brands), or far (regular)";
+        RenderErrorReason::Other(format!(
+            "Unknown Font Awesome icon `{name}` for type `{type_}`. \
+             Hint: check the icon name and prefix ({valid_types}) at \
+             https://fontawesome.com/v6/search?m=free"
+        ))
+    })?)?;
     out.write("</span>")?;
 
     Ok(())

tests/testsuite/rendering.rs

@@ -60,6 +60,24 @@ fn fontawesome() {
         .check_all_main_files();
 }
 
+// Verifies that an invalid `git-repository-icon` in book.toml produces a
+// helpful error message with the icon name, type, and a link to FontAwesome.
+#[test]
+fn fontawesome_error_message() {
+    BookTest::from_dir("rendering/fontawesome_error")
+        .run("build", |cmd| {
+            cmd.expect_failure();
+            cmd.expect_stderr(str![[r#"
+ INFO Book building has started
+ INFO Running the html backend
+ERROR Rendering failed
+[TAB]Caused by: Error rendering "index" line [..], col [..]: Unknown Font Awesome icon `github` for type `regular`. Hint: check the icon name and prefix (fas (solid), fab (brands), or far (regular)) at https://fontawesome.com/v6/search?m=free
+[TAB]Caused by: Unknown Font Awesome icon `github` for type `regular`. Hint: check the icon name and prefix (fas (solid), fab (brands), or far (regular)) at https://fontawesome.com/v6/search?m=free
+
+"#]]);
+        });
+}
+
 // Tests the rendering when setting the default rust edition.
 #[test]
 fn default_rust_edition() {

tests/testsuite/rendering/fontawesome_error/book.toml

@@ -0,0 +1,6 @@
+[book]
+title = "fontawesome_error"
+
+[output.html]
+git-repository-url = "https://github.com/example/test"
+git-repository-icon = "fa-github"

tests/testsuite/rendering/fontawesome_error/src/SUMMARY.md

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

tests/testsuite/rendering/fontawesome_error/src/chapter_1.md

@@ -0,0 +1,3 @@
+# Chapter 1
+
+Hello, world!