diff --git a/docs/markdownrules.md b/docs/markdownrules.md
index 6479b2aa2914731d26cbdad392eb4bcbaa0d662a..01072c586e1f324a25ae121557c1f738589d6f66 100644
--- a/docs/markdownrules.md
+++ b/docs/markdownrules.md
@@ -280,7 +280,43 @@ mkdocs**:
 -   More list items
 ````
 
+## Admonitions
 
+### Types
+
+!!! note
+    I am a "note" admonition.
+
+!!! tip
+    I am a "tip" admonition.
+
+!!! warning
+    I am a "warning" admonition.
+
+!!! danger
+    I am a "danger" admonition.
+
+Other types
+
+-   "hint", "important" (visually identical to "tip")
+-   "attention", "caution" (visually identical to "warning")
+-   "error" (visually identical to "danger")
+
+### Syntax
+
+Simple example:
+
+```md
+!!! note
+    This feature is only available as of CiviCRM 4.5.
+```
+
+Add a custom title (make sure to quote the title):
+
+```md
+!!! danger "Don't try this at home!"
+    Stand back. I'm about to try science!
+```
 
 ## Images
 
diff --git a/mkdocs.yml b/mkdocs.yml
index d6af3027ab3650c83f4e3265824e2b6b92309bb0..38de5b6b92fe547545f1a4103fe5f1bf7eb386c9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -3,6 +3,8 @@ repo_url: https://github.com/civicrm/civicrm-dev-docs
 site_description: A guide for CiviCRM developers.
 site_author: The CiviCRM community
 theme: readthedocs
+markdown_extensions:
+  - markdown.extensions.admonition
 pages:
 - Home: index.md
 - Basics: