From c53379e3acf85d207fb62e4c2be4ea9d2043c98e Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 19 Nov 2025 15:56:54 -0800 Subject: [PATCH 1/3] Add a test using full fontawesome type names In version 6, Font Awesome changed so that the class names look like `fa-solid fa-cat` instead of `fas fa-cat`. mdBook is not handling the new style. --- tests/testsuite/rendering.rs | 1 + tests/testsuite/rendering/fontawesome/expected/fa.html | 3 ++- tests/testsuite/rendering/fontawesome/src/fa.md | 2 ++ 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/tests/testsuite/rendering.rs b/tests/testsuite/rendering.rs index 421aa5d45c..63bcc70ff7 100644 --- a/tests/testsuite/rendering.rs +++ b/tests/testsuite/rendering.rs @@ -53,6 +53,7 @@ fn fontawesome() { INFO Book building has started INFO Running the html backend WARN failed to find Font Awesome icon for icon `does-not-exist` with type `regular` in `fa.md`: Invalid Font Awesome icon name: visit https://fontawesome.com/icons?d=gallery&m=free to see valid names + WARN failed to find Font Awesome icon for icon `cat` with type `regular` in `fa.md`: Invalid Font Awesome icon name: visit https://fontawesome.com/icons?d=gallery&m=free to see valid names INFO HTML book written to `[ROOT]/book` "#]]); diff --git a/tests/testsuite/rendering/fontawesome/expected/fa.html b/tests/testsuite/rendering/fontawesome/expected/fa.html index a2f9d4236e..565f7f89d3 100644 --- a/tests/testsuite/rendering/fontawesome/expected/fa.html +++ b/tests/testsuite/rendering/fontawesome/expected/fa.html @@ -3,4 +3,5 @@

Chapter 1

Text prevents translation.

-

\ No newline at end of file +

+

\ No newline at end of file diff --git a/tests/testsuite/rendering/fontawesome/src/fa.md b/tests/testsuite/rendering/fontawesome/src/fa.md index 2f934da18d..1764c91085 100644 --- a/tests/testsuite/rendering/fontawesome/src/fa.md +++ b/tests/testsuite/rendering/fontawesome/src/fa.md @@ -9,3 +9,5 @@ Text prevents translation. + + From 4b5ea14ee1fc11c20b4e228627f73c90b02a6369 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 19 Nov 2025 16:04:34 -0800 Subject: [PATCH 2/3] Support new font-awesome class names In version 6, Font Awesome changed so that the class names look like `fa-solid fa-cat` instead of `fas fa-cat`. This updates so that it handles this new style. --- crates/mdbook-html/src/html/tree.rs | 10 +++++----- tests/testsuite/rendering.rs | 1 - tests/testsuite/rendering/fontawesome/expected/fa.html | 2 +- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/crates/mdbook-html/src/html/tree.rs b/crates/mdbook-html/src/html/tree.rs index 0c7c2e4d10..5cb97ce378 100644 --- a/crates/mdbook-html/src/html/tree.rs +++ b/crates/mdbook-html/src/html/tree.rs @@ -1030,14 +1030,14 @@ where let i_el = node.value().as_element().unwrap(); let classes = i_el.attr("class").unwrap_or_default(); for class in classes.split(" ") { - if let Some(class) = class.strip_prefix("fa-") { - icon = class.to_owned(); - } else if class == "fa" { + if matches!(class, "fa" | "fa-regular") { type_ = fa::Type::Regular; - } else if class == "fas" { + } else if matches!(class, "fas" | "fa-solid") { type_ = fa::Type::Solid; - } else if class == "fab" { + } else if matches!(class, "fab" | "fa-brands") { type_ = fa::Type::Brands; + } else if let Some(class) = class.strip_prefix("fa-") { + icon = class.to_owned(); } else { new_classes += " "; new_classes += class; diff --git a/tests/testsuite/rendering.rs b/tests/testsuite/rendering.rs index 63bcc70ff7..421aa5d45c 100644 --- a/tests/testsuite/rendering.rs +++ b/tests/testsuite/rendering.rs @@ -53,7 +53,6 @@ fn fontawesome() { INFO Book building has started INFO Running the html backend WARN failed to find Font Awesome icon for icon `does-not-exist` with type `regular` in `fa.md`: Invalid Font Awesome icon name: visit https://fontawesome.com/icons?d=gallery&m=free to see valid names - WARN failed to find Font Awesome icon for icon `cat` with type `regular` in `fa.md`: Invalid Font Awesome icon name: visit https://fontawesome.com/icons?d=gallery&m=free to see valid names INFO HTML book written to `[ROOT]/book` "#]]); diff --git a/tests/testsuite/rendering/fontawesome/expected/fa.html b/tests/testsuite/rendering/fontawesome/expected/fa.html index 565f7f89d3..6dfc9de1f8 100644 --- a/tests/testsuite/rendering/fontawesome/expected/fa.html +++ b/tests/testsuite/rendering/fontawesome/expected/fa.html @@ -4,4 +4,4 @@

Chapter 1

Text prevents translation.

-

\ No newline at end of file +

\ No newline at end of file From 8571d70b52e69df3b571993fd628b86e63c59da0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 19 Nov 2025 16:15:53 -0800 Subject: [PATCH 3/3] Update the documentation for Font Awesome This updates the documentation to try to improve the Font Awesome support. --- CHANGELOG.md | 2 +- guide/src/format/configuration/renderers.md | 4 +--- guide/src/format/mdbook.md | 8 +++++--- guide/src/format/theme/index-hbs.md | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 53c02a3107..560bef26b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -75,7 +75,7 @@ The following is a summary of the changes that may require your attention when u - Updated to a newer version of `pulldown-cmark`. This brings a large number of fixes to markdown processing. [#2401](https://github.com/rust-lang/mdBook/pull/2401) -- The font-awesome font is no longer loaded as a font. Instead, the corresponding SVG is embedded in the output for the corresponding `` tags. Additionally, a handlebars helper has been added for the `hbs` files. +- The font-awesome font is no longer loaded as a font. Instead, the corresponding SVG is embedded in the output for the corresponding `` tags. Additionally, a handlebars helper has been added for the `hbs` files. This also updates the version from 4.7.0 to 6.2.0, which means some of the icon names and styles have changed. Most of the free icons are in the "solid" set. See the [free icon set](https://fontawesome.com/v6/search) for the available icons. [#1330](https://github.com/rust-lang/mdBook/pull/1330) - Changed all internal HTML IDs to have an `mdbook-` prefix. This helps avoid namespace conflicts with header IDs. [#2808](https://github.com/rust-lang/mdBook/pull/2808) diff --git a/guide/src/format/configuration/renderers.md b/guide/src/format/configuration/renderers.md index ae0b724a4b..22dfd425fb 100644 --- a/guide/src/format/configuration/renderers.md +++ b/guide/src/format/configuration/renderers.md @@ -143,9 +143,7 @@ The following configuration options are available: those labels. Defaults to `false`. - **git-repository-url:** A url to the git repository for the book. If provided an icon link will be output in the menu bar of the book. -- **git-repository-icon:** The FontAwesome icon class to use for the git - repository link. Defaults to `fab-github` which looks like . - If you are not using GitHub, another option to consider is `fa-code-fork` which looks like . +- **git-repository-icon:** The Font Awesome icon class to use for the git repository link. Defaults to `fab-github` which looks like . If you are not using GitHub, another option to consider is `fas-code-fork` which looks like . The start of the string should be `fa-` for regular icons, `fas-` for solid icons, or `fab-` for brand icons. See the [free icon set](https://fontawesome.com/v6/search) for the available icons. - **edit-url-template:** Edit url template, when provided shows a "Suggest an edit" button (which looks like ) for directly jumping to editing the currently viewed page. For e.g. GitHub projects set this to diff --git a/guide/src/format/mdbook.md b/guide/src/format/mdbook.md index ff63eb43a9..9401107eb2 100644 --- a/guide/src/format/mdbook.md +++ b/guide/src/format/mdbook.md @@ -340,7 +340,7 @@ HTML tags with class `hidden` will not be shown. ## Font-Awesome icons -mdBook includes a copy of [Font Awesome Free's](https://fontawesome.com) +mdBook includes a copy of version 6 of [Font Awesome Free's](https://fontawesome.com) MIT-licensed SVG files. It emulates the `` syntax, but converts the results to inline SVG. Only the regular, solid, and brands icons are included; paid features like the light icons are not. @@ -348,7 +348,9 @@ features like the light icons are not. For example, given this HTML syntax: ```hbs -The result looks like this: +The result looks like this: ``` -The result looks like this: +The result looks like this: + +See the [free icon set](https://fontawesome.com/v6/search) for the available icons. diff --git a/guide/src/format/theme/index-hbs.md b/guide/src/format/theme/index-hbs.md index 16e14b2c07..35e8b03637 100644 --- a/guide/src/format/theme/index-hbs.md +++ b/guide/src/format/theme/index-hbs.md @@ -95,7 +95,7 @@ MIT-licensed SVG files. It accepts three positional arguments: 1. Type: one of "solid", "regular", and "brands" (light and duotone are not currently supported) 2. Icon: anything chosen from the - [free icon set](https://fontawesome.com/icons?d=gallery&m=free) + [free icon set](https://fontawesome.com/v6/search) 3. ID (optional): if included, an HTML ID attribute will be added to the icon's wrapping `` tag