help: Enable and use the markdown admonition extension.

This allows us to add warnings and tips in the Zulip help documents.

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.

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

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