Added documentation for custom admonition icons

CHANGELOG

@@ -1,3 +1,8 @@
+mkdocs-material-7.0.6+insiders-2.4.0 (2021-03-20)
+
+  * Added support for custom admonition icons
+  * Fixed #2444: Code block annotations with extra comments have wrong index
+
 mkdocs-material-7.0.6+insiders-2.3.1 (2021-03-14)
 
   * Fixed anchor offset for permalinks when using sticky navigation tabs

docs/changelog/insiders.md

@@ -6,6 +6,11 @@ template: overrides/main.html
 
 ## Material for MkDocs Insiders
 
+### 2.4.0 <small>_ March 20, 2021</small>
+
+- Added support for custom admonition icons
+- Fixed #2444: Code block annotations with extra comments have wrong index
+
 ### 2.3.1 <small>_ March 14, 2021</small>
 
 - Fixed anchor offset for permalinks when using sticky navigation tabs

docs/insiders.md

@@ -110,9 +110,10 @@ The following features are currently exclusively available to sponsors:
 
 <div class="mdx-columns" markdown="1">
 
+- [x] [Custom admonition icons :material-new-box:][27]
 - [x] [Code block annotations :material-new-box:][25]
-- [x] [Anchor tracking :material-new-box:][24]
 - [x] [Back-to-top button :material-new-box:][17]
+- [x] [Anchor tracking ][24]
 - [x] [Section index pages][22]
 - [x] [Latest release tag][15]
 - [x] [Color palette toggle][16]
@@ -198,13 +199,21 @@ the public for general availability.
 - [ ] Table of contents follows active anchor
 - [ ] Native lightbox integration
 
+#### $ 8,000 - Scotch Bonnet
+
+- [x] [Custom admonition icons][27]
+- [ ] TBA
+- [ ] TBA
+
+  [27]: reference/admonitions.md#changing-the-icons
+
 #### Future
 
-- [ ] [Material for MkDocs Live Edit][27]
+- [ ] [Material for MkDocs Live Edit][28]
 - [ ] New layouts and styles
 - [ ] Code block palette toggle
 
-  [27]: https://twitter.com/squidfunk/status/1338252230265360391
+  [28]: https://twitter.com/squidfunk/status/1338252230265360391
 
 ### Goals completed
 
@@ -250,10 +259,10 @@ implemented behind feature flags; all configuration changes are
 backward-compatible. This means that your users will be able to build the
 documentation locally with Material for MkDocs and when they push their changes,
 it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's
-recommended to [install Insiders][28] only in CI, as you don't want to expose
+recommended to [install Insiders][29] only in CI, as you don't want to expose
 your `GH_TOKEN` to users.
 
-  [28]: publishing-your-site.md#github-pages
+  [29]: publishing-your-site.md#github-pages
 
 ### Terms
 
@@ -262,7 +271,7 @@ commercial project. Can we use Insiders under the same terms and conditions?_
 
 Yes. Whether you're an individual or a company, you may use _Material for MkDocs
 Insiders_ precisely under the same terms as Material for MkDocs, which are given
-by the [MIT license][29]. However, we kindly ask you to respect the following
+by the [MIT license][30]. However, we kindly ask you to respect the following
 guidelines:
 
 - Please __don't distribute the source code__ of Insiders. You may freely use
@@ -273,7 +282,7 @@ guidelines:
 - If you cancel your subscription, you're removed as a collaborator and will
   miss out on future updates of Insiders. However, you may __use the latest
   version__ that's available to you __as long as you like__. Just remember that
-  [GitHub deletes private forks][30].
+  [GitHub deletes private forks][31].
 
-  [29]: license.md
+  [30]: license.md
-  [30]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
+  [31]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

docs/reference/admonitions.md

@@ -384,13 +384,78 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
+### Changing the icons
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][13]{ .mdx-insiders }
+
+Each of the supported admonition types has a distinct icon, which can be changed
+to any icon bundled with the theme. Just set the name of the admonition type to
+a valid icon in `mkdocs.yml`:
+
+=== "Octicons"
+
+    _Example_:
+
+    ``` yaml
+    theme:
+      icon:
+        admonition:
+          note: octicons/tag-16
+          abstract: octicons/checklist-16
+          info: octicons/info-16
+          tip: octicons/squirrel-16
+          success: octicons/check-16
+          question: octicons/question-16
+          warning: octicons/alert-16
+          failure: octicons/x-circle-16
+          danger: octicons/zap-16
+          bug: octicons/bug-16
+          example: octicons/beaker-16
+          quote: octicons/quote-16
+    ```
+
+    _Result_:
+
+    [![Admonition with Octicons icons][14]][14]
+
+
+=== "FontAwesome"
+
+    _Example_:
+
+    ``` yaml
+    theme:
+      icon:
+        admonition:
+          note: fontawesome/solid/sticky-note
+          abstract: fontawesome/solid/book
+          info: fontawesome/solid/info-circle
+          tip: fontawesome/solid/bullhorn
+          success: fontawesome/solid/check
+          question: fontawesome/solid/question-circle
+          warning: fontawesome/solid/exclamation-triangle
+          failure: fontawesome/solid/bomb
+          danger: fontawesome/solid/skull
+          bug: fontawesome/solid/robot
+          example: fontawesome/solid/flask
+          quote: fontawesome/solid/quote-left
+    ```
+
+    _Result_:
+
+    [![Admonition with FontAwesome icons][15]][15]
+
+  [13]: ../insiders.md
+  [14]: ../assets/screenshots/admonition-octicons.png
+  [15]: ../assets/screenshots/admonition-fontawesome.png
+
 ## Customization
 
 ### Custom admonitions
 
 If you want to add a custom admonition type, all you need is a color and an
-`svg` icon. Copy the icon's `svg` code from the [`.icons`][13] folder and add the
+`svg` icon. Copy the icon's `svg` code from the [`.icons`][16] folder and add the
-following CSS to an [additional stylesheet][14]:
+following CSS to an [additional stylesheet][17]:
 
 ``` css
 :root {
@@ -415,7 +480,7 @@ following CSS to an [additional stylesheet][14]:
 
 You should now be able to create an admonition of the `pied-piper` type. Note
 that you can also use this technique to override existing admonition icons or
-colors. [You can even add animations][15].
+colors. [You can even add animations][18].
 
 <style>
   :root {
@@ -455,6 +520,6 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
-  [13]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [16]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
-  [14]: ../customization.md#additional-css
+  [17]: ../customization.md#additional-css
-  [15]: ./icons-emojis.md#with-animations
+  [18]: icons-emojis.md#with-animations

docs/upgrading.md

@@ -642,7 +642,7 @@ flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:
 #### `theme.logo.icon`
 
 The logo icon configuration was centralized under `theme.icon.logo` and can now
-be set to any of the [icons bundled with the theme][3]:
+be set to any of the [icons bundled with the theme][6]:
 
 === "5.x"
 
@@ -663,7 +663,7 @@ be set to any of the [icons bundled with the theme][3]:
 #### `extra.repo_icon`
 
 The repo icon configuration was centralized under `theme.icon.repo` and can now
-be set to any of the [icons bundled with the theme][3]:
+be set to any of the [icons bundled with the theme][6]:
 
 === "5.x"