Add font-awesome access and docs for book content

guide/src/format/mdbook.md

@@ -274,3 +274,18 @@ contents (sidebar) by including a `\{{#title ...}}` near the top of the page.
 ```hbs
 \{{#title My Title}}
 ```
+
+## Font-Awesome icons
+
+mdBook includes a copy of [Font Awesome Free's](https://fontawesome.com)
+MIT-licensed SVG files. It emulates the `<i class="fa">` 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.
+
+For example, given this HTML syntax:
+
+```hbs
+The result looks like this: <i class="fas fa-print"></i>
+```
+
+The result looks like this: <i class="fas fa-print"></i>

guide/src/format/theme/index-hbs.md

@@ -99,3 +99,25 @@ Of course the inner html can be changed to your liking.
 
 *If you would like other properties or helpers exposed, please [create a new
 issue](https://github.com/rust-lang/mdBook/issues)*
+
+### 3. fa
+
+mdBook includes a copy of [Font Awesome Free's](https://fontawesome.com)
+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)
+3. ID (optional): if included, an HTML ID attribute will be added to the
+   icon's wrapping `<span>` tag
+
+For example, this handlebars syntax will become this HTML:
+
+```handlebars
+{{fa "solid" "print" "print-button"}}
+```
+
+```html
+<span class=fa-svg id="print-button"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M448 192V77.25c0-8.49-3.37-16.62-9.37-22.63L393.37 9.37c-6-6-14.14-9.37-22.63-9.37H96C78.33 0 64 14.33 64 32v160c-35.35 0-64 28.65-64 64v112c0 8.84 7.16 16 16 16h48v96c0 17.67 14.33 32 32 32h320c17.67 0 32-14.33 32-32v-96h48c8.84 0 16-7.16 16-16V256c0-35.35-28.65-64-64-64zm-64 256H128v-96h256v96zm0-224H128V64h192v48c0 8.84 7.16 16 16 16h48v96zm48 72c-13.25 0-24-10.75-24-24 0-13.26 10.75-24 24-24s24 10.74 24 24c0 13.25-10.75 24-24 24z"/></svg></span>
+```

src/renderer/html_handlebars/hbs_renderer.rs

@@ -200,6 +200,7 @@ impl HtmlHandlebars {
         let rendered = build_header_links(&rendered);
         let rendered = fix_code_blocks(&rendered);
         let rendered = add_playground_pre(&rendered, playground_config, edition);
+        let rendered = convert_fontawesome(&rendered);
 
         rendered
     }
@@ -767,6 +768,54 @@ fn insert_link_into_header(
     )
 }
 
+// Convert fontawesome `<i>` tags to inline SVG
+fn convert_fontawesome(html: &str) -> String {
+    use font_awesome_as_a_crate as fa;
+
+    let regex = Regex::new(r##"<i([^>]+)class="([^"]+)"([^>]*)></i>"##).unwrap();
+    regex
+        .replace_all(html, |caps: &Captures<'_>| {
+            let text = &caps[0];
+            let before = &caps[1];
+            let classes = &caps[2];
+            let after = &caps[3];
+
+            let mut icon = String::new();
+            let mut type_ = fa::Type::Regular;
+            let mut other_classes = String::new();
+
+            for class in classes.split(" ") {
+                if class.starts_with("fa-") {
+                    icon = class[3..].to_owned();
+                } else if class == "fa" {
+                    type_ = fa::Type::Regular;
+                } else if class == "fas" {
+                    type_ = fa::Type::Solid;
+                } else if class == "fab" {
+                    type_ = fa::Type::Brands;
+                } else {
+                    other_classes += " ";
+                    other_classes += class;
+                }
+            }
+
+            if icon == "" {
+                text.to_owned()
+            } else if let Ok(svg) = fa::svg(type_, &icon) {
+                format!(
+                    r#"<span{before}class="fa-svg{other_classes}"{after}>{svg}</span>"#,
+                    before = before,
+                    other_classes = other_classes,
+                    after = after,
+                    svg = svg
+                )
+            } else {
+                text.to_owned()
+            }
+        })
+        .into_owned()
+}
+
 // The rust book uses annotations for rustdoc to test code snippets,
 // like the following:
 // ```rust,should_panic