diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index d582d570e..fada17fea 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -325,3 +325,76 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
+
+## 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`][9] folder and add the
+following CSS to an [additional stylesheet][10]:
+
+``` css
+:root {
+ --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,')
+}
+.md-typeset .admonition.pied-piper,
+.md-typeset details.pied-piper {
+ border-color: rgb(43, 155, 70);
+}
+.md-typeset .pied-piper > .admonition-title,
+.md-typeset .pied-piper > summary {
+ background-color: rgba(43, 155, 70, 0.1);
+}
+.md-typeset .pied-piper > .admonition-title::before,
+.md-typeset .pied-piper > summary::before {
+ background-color: rgb(43, 155, 70);
+ -webkit-mask-image: var(--md-admonition-icon--pied-piper);
+ mask-image: var(--md-admonition-icon--pied-piper);
+}
+```
+
+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][11].
+
+
+
+_Example_:
+
+``` markdown
+!!! pied-piper "Pied Piper"
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+_Result_:
+
+!!! pied-piper "Pied Piper"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+ [9]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+ [10]: ../customization.md#additional-stylesheets
+ [11]: icons-emojis.md#with-animations
diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md
index 284629ab8..b458b860d 100644
--- a/docs/reference/icons-emojis.md
+++ b/docs/reference/icons-emojis.md
@@ -124,7 +124,7 @@ an [additional stylesheet][19] and put styles into dedicated CSS classes:
}
```
-Then, add the CSS classes to the icons:
+Then, simply add the CSS class to the icon.