Improved discoverability of icons in the documentation

docs/setup/adding-a-git-repository.md

@@ -56,15 +56,26 @@ repo_name: squidfunk/mkdocs-material
 [`fontawesome/brands/git-alt`][icon.repo default]
 
 While the default repository icon is a generic git icon, it can be set to
-[any icon bundled with the theme][custom icons] by referencing a valid icon
-path in `mkdocs.yml`:
+any icon bundled with the theme by referencing a valid icon path in
+`mkdocs.yml`:
 
 ``` yaml
 theme:
   icon:
-    repo: fontawesome/brands/git-alt
+    repo: fontawesome/brands/git-alt # (1)
 ```
 
+1.  Enter a few keywords to find the perfect icon using our [icon search] and
+    click on the shortcode to copy it to your clipboard:
+
+    <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+      <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="git" />
+      <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+        <div class="mdx-iconsearch-result__meta"></div>
+        <ol class="mdx-iconsearch-result__list"></ol>
+      </div>
+    </div>
+
 Some popular choices:
 
 - :fontawesome-brands-git: – `fontawesome/brands/git`
@@ -80,7 +91,7 @@ Some popular choices:
 
   [icon.repo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
   [icon.repo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg
-  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [icon search]: ../reference/icons-emojis.md#search
 
 ### Edit button
 

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

@@ -34,11 +34,23 @@ Add the following lines to `mkdocs.yml`:
     ``` yaml
     theme:
       icon:
-        logo: material/library
+        logo: material/library # (1)!
     ```
 
+    1.  Enter a few keywords to find the perfect icon using our [icon search] and
+        click on the shortcode to copy it to your clipboard:
+
+        <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+          <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="material library" />
+          <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+            <div class="mdx-iconsearch-result__meta"></div>
+            <ol class="mdx-iconsearch-result__list"></ol>
+          </div>
+        </div>
+
   [logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [logo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg
+  [icon search]: ../reference/icons-emojis.md#search
 
 Normally, the logo in the header and sidebar links to the homepage of the
 documentation, which is the same as `site_url`. This behavior can be changed

docs/setup/setting-up-the-footer.md

@@ -25,17 +25,28 @@ with:
 ``` yaml
 extra:
   social:
-    - icon: fontawesome/brands/twitter
+    - icon: fontawesome/brands/twitter # (1)!
       link: https://twitter.com/squidfunk
 ```
 
+1.  Enter a few keywords to find the perfect icon using our [icon search] and
+    click on the shortcode to copy it to your clipboard:
+
+    <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+      <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="brands twitter" />
+      <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+        <div class="mdx-iconsearch-result__meta"></div>
+        <ol class="mdx-iconsearch-result__list"></ol>
+      </div>
+    </div>
+
 The following properties must be set for each link:
 
 `icon`{ #social-icon }
 
 :   [:octicons-tag-24: 5.0.0][social.icon support] · :octicons-milestone-24:
     Default: _none_ · :octicons-alert-24: Required – This property must contain
-    a valid path to [any icon bundled with the theme][custom icons], or the
+    a valid path to any icon bundled with the theme, or the
     build will not succeed. Some popular choices:
 
     * :fontawesome-brands-behance: – `fontawesome/brands/behance`
@@ -91,7 +102,6 @@ The following properties must be set for each link:
   [social support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [social.icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
   [social.name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.1.5
-  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
 
 ### Copyright notice