Improved discoverability of icons in the documentation

Author: squidfunk

docs/reference/admonitions.md

@@ -49,8 +49,16 @@ theme:
       <type>: <icon> # (1)!
 ```
 
-1.  Set `<type`> to any of the [supported types] and `<icon>` to any valid icon 
-    shortcode, which you can find by using the [icon search].
+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="alert" />
+      <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>
 
 ??? example "Expand to show alternate icon sets"
 

docs/reference/buttons.md

@@ -69,7 +69,7 @@ CSS class selectors.
 ### Adding icon buttons
 
 Of course, icons can be added to all types of buttons by using the [icon syntax]
-together with any valid icon shortcode, which can be easily found with a few keystrokes through the [icon search].
+together with any valid icon shortcode, which can be easily found with a few keystrokes through our [icon search].
 
 ``` markdown title="Button with icon"
 [Send :fontawesome-solid-paper-plane:](#){ .md-button }

docs/reference/icons-emojis.md

@@ -198,10 +198,21 @@ reference any icon that's [bundled with the theme][icon search] with Jinja's
 
 ``` html
 <span class="twemoji">
-  {% include ".icons/fontawesome/brands/twitter.svg" %}
+  {% include ".icons/fontawesome/brands/twitter.svg" %} <!-- (1)! -->
 </span>
 ```
 
+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>
+
 This is exactly what Material for MkDocs does in its templates.
 
   [extending the theme]: ../customization.md#extending-the-theme

docs/reference/index.md

@@ -88,8 +88,16 @@ icon: material/emoticon-happy # (1)!
 ...
 ```
 
-1.  Check out the left sidebar to see icons in action! Also check out our
-    [icon search] to find the perfect icon with a few keystrokes.
+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="emoticon happy" />
+      <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>
 
   [Insiders]: ../insiders/index.md
   [icon search]: icons-emojis.md#search

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