Added guide on custom icon integration

docs/creating-your-site.md

@@ -29,6 +29,7 @@ If you're running Material for MkDocs from within Docker, use:
 This will create the following structure:
 
 ```
+.
 ├─ docs/
 │  └─ index.md
 └─ mkdocs.yml

docs/setup/changing-the-colors.md

@@ -10,7 +10,7 @@ Google's original [color palette][1], which can be easily configured through
 fit your brand's identity by using [CSS variables][2].
 
   [1]: http://www.materialui.co/colors
-  [2]: #customization
+  [2]: #custom-colors
 
 ## Configuration
 
@@ -184,7 +184,7 @@ color:
 
 ## Customization
 
-### Brand colors
+### Custom colors
 
 [:octicons-file-code-24: Source][6] ·
 :octicons-mortar-board-24: Difficulty: _easy_

docs/setup/changing-the-fonts.md

@@ -58,10 +58,10 @@ If you want to load fonts from other destinations or don't want to use Google
 Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize
 font loading as described below.
 
-### Disable font loading
+### Disabling font loading
 
 [:octicons-file-code-24: Source][2] ·
-:octicons-mortar-board-24: Difficulty: _none_
+:octicons-mortar-board-24: Difficulty: _easy_
 
 If you want to prevent typefaces from being loaded from Google Fonts and fall
 back to system fonts, add the following lines to `mkdocs.yml`:
@@ -87,11 +87,10 @@ corresponding `@font-face` definition:
 }
 ```
 
-The font can then be configured to be used globally as the regular or
-proportional font, or limited to be used for specific elements only, e.g.
-headlines:
+The font can then be applied to specific elements, e.g. only headlines, or 
+globally to be used as the site-wide regular or proportional font:
 
-=== "Body copy"
+=== "Regular font"
 
     ``` css
     body, input {
@@ -99,15 +98,7 @@ headlines:
     }
     ```
 
-=== "Headlines"
-
-    ``` css
-    .md-typeset h1 {
-      font-family: "<font>", -apple-system, Helvetica, Arial, sans-serif;
-    }
-    ```
-
-=== "Code blocks"
+=== "Proportional font"
 
     ``` css
     pre, code, kbd {

docs/setup/changing-the-logo-and-icons.md

@@ -1 +1,130 @@
-Icons are all inlined!
+---
+template: overrides/main.html
+---
+
+# Changing the logo and icons
+
+When installing Material for MkDocs, you immediately get access to _over 7.000 
+icons_ ready to be used for customization of specific parts of the theme and/or 
+when writing your documentation in Markdown. Not enough? You can also [add
+additional icons][1] with very little effort.
+
+  [1]: #additional-icons
+
+## Configuration
+
+### Logo
+
+[:octicons-file-code-24: Source][2] ·
+:octicons-milestone-24: Default: `material/library`
+
+There're two ways to specify a _logo_: it must be a valid path to [any icon 
+bundled with the theme][3], or to a user-provided image located in the `docs`
+folder. Both can be set from `mkdocs.yml`:
+
+=== "Icon"
+
+    ``` yaml
+    theme:
+      icon:
+        logo: material/library
+    ```
+
+=== "Image"
+
+    ``` yaml
+    theme:
+      logo: assets/logo.png
+    ```
+
+  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/logo.html
+  [3]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+
+### Favicon
+
+[:octicons-file-code-24: Source][4] ·
+:octicons-milestone-24: Default: `assets/images/favicon.png`
+
+The _favicon_ can be changed to a path pointing to a user-provided image, which 
+must be located in the `docs` folder. It can be set from `mkdocs.yml`:
+
+``` yaml
+theme:
+  favicon: images/favicon.png
+```
+
+  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L71
+
+### Emoji (icons)
+
+[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]
+
+The [Emoji][6] extension, which is part of [Python Markdown Extensions][7],
+adds the ability to __integrate custom icons__ in the `*.svg` file format,
+which are inlined into the HTML when [building your site][8]:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+```
+
+The following icon sets are bundled with Material for MkDocs:
+
+* :material-material-design: – [Material Design][9]
+* :fontawesome-brands-font-awesome-flag: – [FontAwesome][10]
+* :fontawesome-brands-github: – [Octicons][11]
+
+If you want to add [additional icons][1], read on.
+
+  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_emoji.scss
+  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
+  [7]: https://facelessuser.github.io/pymdown-extensions/
+  [8]: ../creating-your-site.md#building-your-site
+  [9]: https://materialdesignicons.com/
+  [10]: https://fontawesome.com/icons?d=gallery&m=free
+  [11]: https://octicons.github.com/
+
+## Customization
+
+### Additional icons
+
+[:octicons-file-code-24: Source][3] · 
+:octicons-mortar-board-24: Difficulty: _moderate_
+
+In order to add additional icons, [extend the theme][13] and create a folder
+named `.icons` in the [`custom_dir`][14] you want to use for overrides. Next,
+add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say you 
+downloaded and unpacked the [Bootstrap][15] icon set, and want to add it to
+your project documentation. The structure of your project should look like this:
+
+``` sh
+.
+├─ docs/
+│  └─ index.md
+├─ overrides/
+│  └─ .icons/
+│     └─ bootstrap/
+│        └─ *.svg
+└─ mkdocs.yml
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+      options:
+        custom_icons:
+          - overrides/.icons
+```
+
+You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap
+icons.
+
+  [13]: ../customization.md#extending-the-theme
+  [14]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
+  [15]: https://icons.getbootstrap.com/