Use embedded SVG instead of fonts for icons

The [downsides of icon fonts] are well-documented, and also, why ship all of
the icons when it only uses 14?

[downsides of icon fonts]: https://speakerdeck.com/ninjanails/death-to-icon-fonts

guide/src/format/configuration/renderers.md

@@ -103,7 +103,7 @@ additional-css = ["custom.css", "custom2.css"]
 additional-js = ["custom.js"]
 no-section-label = false
 git-repository-url = "https://github.com/rust-lang/mdBook"
-git-repository-icon = "fa-github"
+git-repository-icon = "fab-github"
 edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}"
 site-url = "/example-book/"
 cname = "myproject.rs"
@@ -139,7 +139,7 @@ The following configuration options are available:
 - **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 `fa-github` which looks like <i class="fa fa-github"></i>.
+  repository link. Defaults to `fab-github` which looks like <i class="fa fab-github"></i>.
   If you are not using GitHub, another option to consider is `fa-code-fork` which looks like <i class="fa fa-code-fork"></i>.
 - **edit-url-template:** Edit url template, when provided shows a
   "Suggest an edit" button (which looks like <i class="fa fa-edit"></i>) for directly jumping to editing the currently

guide/src/format/mdbook.md

@@ -363,3 +363,18 @@ fatigue," where people are trained to ignore them because they usually don't
 matter for what they're doing.
 
 </div>
+
+## Font-Awesome icons
+
+mdBook includes a copy of [Font Awesome Free's](https://fontawesome.com)
+MIT-licensed SVG files. It emulates the `<i>` 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

@@ -86,3 +86,25 @@ and accounts for files that are renamed with a hash in their filename.
 ```handlebars
 <link rel="stylesheet" href="{{ resource "css/chrome.css" }}">
 ```
+
+### 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>
+```

guide/src/guide/reading.md

@@ -30,12 +30,12 @@ The icons displayed will depend on the settings of how the book was generated.
 
 | Icon | Description |
 |------|-------------|
-| <i class="fa fa-bars"></i> | Opens and closes the chapter listing sidebar. |
-| <i class="fa fa-paint-brush"></i> | Opens a picker to choose a different color theme. |
-| <i class="fa fa-search"></i> | Opens a search bar for searching within the book. |
-| <i class="fa fa-print"></i> | Instructs the web browser to print the entire book. |
-| <i class="fa fa-github"></i> | Opens a link to the website that hosts the source code of the book. |
-| <i class="fa fa-edit"></i> | Opens a page to directly edit the source of the page you are currently reading. |
+| <i class="fas fa-bars"></i> | Opens and closes the chapter listing sidebar. |
+| <i class="fas fa-paintbrush"></i> | Opens a picker to choose a different color theme. |
+| <i class="fas fa-magnifying-glass"></i> | Opens a search bar for searching within the book. |
+| <i class="fas fa-print"></i> | Instructs the web browser to print the entire book. |
+| <i class="fab fa-github"></i> | Opens a link to the website that hosts the source code of the book. |
+| <i class="fas fa-pencil"></i> | Opens a page to directly edit the source of the page you are currently reading. |
 
 Tapping the menu bar will scroll the page to the top.
 
@@ -59,9 +59,9 @@ Code blocks may contain several different icons for interacting with them:
 | Icon | Description |
 |------|-------------|
 | <i class="fa fa-copy"></i> | Copies the code block into your local clipboard, to allow pasting into another application. |
-| <i class="fa fa-play"></i> | For Rust code examples, this will execute the sample code and display the compiler output just below the example (see [playground]). |
+| <i class="fas fa-play"></i> | For Rust code examples, this will execute the sample code and display the compiler output just below the example (see [playground]). |
 | <i class="fa fa-eye"></i> | For Rust code examples, this will toggle visibility of "hidden" lines. Sometimes, larger examples will hide lines which are not particularly relevant to what is being illustrated (see [hiding code lines]). |
-| <i class="fa fa-history"></i> | For [editable code examples][editor], this will undo any changes you have made. |
+| <i class="fas fa-clock-rotate-left"></i> | For [editable code examples][editor], this will undo any changes you have made. |
 
 Here's an example: