diff --git a/docs/README.md b/docs/README.md
index b88a378c8f..53f49e7c75 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -115,6 +115,20 @@ below.
 ### Supported features
 
 * All the usual features of Markdown with raw HTML enabled so you can
-  do custom things as needed.
-* Code blocks with syntax highlighting.
+  do custom things with HTML/CSS as needed.  The goal is to make
+  reusable markdown syntax for things we need often, though.
+* Code blocks with syntax highlighting, similar to Zulip's own markdown.
 * Anchor tags for linking to headers in other documents.
+* You can create special highlight warning blocks using e.g.:
+```
+!!! warn "title of warning"
+    Body of warning
+```
+
+  to create a special warning block with title "title of warning" to
+  highlight something important.  The whitespace is important.  Often,
+  we just use "" as the title.  `!!! tip "title"` is useful for less
+  scary tips.  See
+  [the python-markdown docs on this extension](https://pythonhosted.org/Markdown/extensions/admonition.html)
+  for details on how this extension works; essentially the value
+  `warn` or `tip` is an extra CSS class added to the admonition.
diff --git a/templates/zerver/help/index.md b/templates/zerver/help/index.md
index ca381e354f..0ef60a86f9 100644
--- a/templates/zerver/help/index.md
+++ b/templates/zerver/help/index.md
@@ -1,13 +1,12 @@
 # Zulip User Documentation (draft)
 
-<span class="warn">
-**Caveat**: This file is intended to collect all proposed user
-documentation into one place. Ultimately, a single file is probably
-not the best format for documentation when it is published to the
-world, but for purposes of discussion it seems easiest to put
-everything into a solitary and linear page.
-</span>
----
+!!! warn ""
+    **Caveat**: This file is intended to collect all proposed user
+    documentation into one place. Ultimately, a single file is probably
+    not the best format for documentation when it is published to the
+    world, but for purposes of discussion it seems easiest to put
+    everything into a solitary and linear page.
+
 
 Zulip is a chat app. Its most distinctive characteristic is that
 conversation among a group of people can be divided according to
diff --git a/zerver/templatetags/app_filters.py b/zerver/templatetags/app_filters.py
index e1d1c6b5ed..10eb1d516f 100644
--- a/zerver/templatetags/app_filters.py
+++ b/zerver/templatetags/app_filters.py
@@ -7,6 +7,7 @@ from zerver.lib.utils import force_text
 import zerver.lib.bugdown.fenced_code
 
 import markdown
+import markdown.extensions.admonition
 import markdown.extensions.codehilite
 import markdown.extensions.toc
 
@@ -65,6 +66,7 @@ def render_markdown_path(markdown_file_path):
     if md_extensions is None:
         md_extensions = [
             markdown.extensions.toc.makeExtension(),
+            markdown.extensions.admonition.makeExtension(),
             markdown.extensions.codehilite.makeExtension(
                 linenums=False,
                 guess_lang=False