diff --git a/README.md b/README.md
index 4a6cc25e36a7071195faded0498d33f28f99f964..f90c5d509e342782e9a606c8e68b6fc69d89e1b3 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,7 @@
-# CiviCRM developer documentation
+# CiviCRM Developer Guide
 
-```bash
-git clone https://github.com/civicrm/civicrm-dev-docs
-cd civicrm-dev-docs
-mkdocs serve
-```
+-   [Read published version](http://docs.civicrm.org/dev/en/master)
+-   [Learn how to edit](https://docs.civicrm.org/dev/en/master/documentation/#how-to-edit)
 
-This will likely be merged with the `civicrm-core` repo at some point.
-
-# See also
-
- * Download mkdocs: http://mkdocs.org/
- * Browse published dev docs: http://docs.civicrm.org/dev/en/master
- * Review general info about CiviCRM docs: https://github.com/civicrm/civicrm-docs
+This Developer Guide will likely be merged into the
+[civicrm-core](https://github.com/civicrm/civicrm-core/) repo at some point.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 1f133bcd094d554411811e69dc30a86171313593..dd90c6b0bbfa3ecba9facc26498c9ac0888c1a8c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -32,30 +32,3 @@ to help out!
 [wiki]: http://wiki.civicrm.org/confluence/display/CRMDOC/Develop
 [migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
 
-## Other sources of information
-
-As an open-source project, CiviCRM is managed by an international community of
-developers and activists. Help from these people can be found in the following
-ways:
-
--   Our [chat rooms](https://chat.civicrm.org/) and
-    [mailing lists](http://lists.civicrm.org/lists/info/civicrm-dev) are great
-    places to say hello and discuss CiviCRM issues with others.
-
--   If you need help, your best bet is probably our
-    [stack exchange Q+A site](http://civicrm.stackexchange.com/).
-
--   If you've identified a problem, you can file issues on our
-    [issue](http://issues.civicrm.org/) on our issue tracker or fix the issue
-    and submit a pull request on
-    [Github](https://github.com/civicrm/civicrm-core/).
-
--   If you've written an extension, please share it in our
-    [extensions directory](https://civicrm.org).
-
--   Use the [wiki](http://wiki.civicrm.org/confluence/display/CRM/CiviCRM+Wiki)
-    to share drafts, notes, and specs.
-
--   And don't forget you are always welcome to come to a
-    [real world event](https://civicrm.org/events) like a conference meet-up
-    or sprint.
diff --git a/docs/markdownrules.md b/docs/markdownrules.md
index 04afdee7ef502734faf86d33e7431b4a5f392825..ca7f1986b951667bc512392a64236d4727009427 100644
--- a/docs/markdownrules.md
+++ b/docs/markdownrules.md
@@ -32,10 +32,17 @@ platforms.
 
 ## Hyperlinks
 
--   A basic hyperlink
+-   A basic hyperlink (in a sentence)
 
         Try [CiviCRM](https://civicrm.org) for your database.
 
+-   An internal hyperlink on mkdocs (4 different ways that all work)
+
+        [extensions](/extensions/basics)
+        [extensions](/extensions/basics.md)
+        [extensions](extensions/basics)
+        [extensions](extensions/basics.md)
+
 -   With long URLs, the following syntax is better.
 
         See [this issue][CRM-19799] for more details.
@@ -85,7 +92,10 @@ This is a second.
 #### Heading 4
 ```
 
-Alternate syntax (only works for h1 and h2):
+The above syntax is [called](http://pandoc.org/MANUAL.html#headers)
+"ATX style headers" in markdown terminology, and is preferred my most.
+An alternate syntax called "setext style headers" works for h1 and h2 as
+follows:
 
 ```md
 Heading 1
@@ -272,7 +282,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 616a5fbfb444e7b2e06969810634a0a20f2ab8cc..9eeaf56b866217f20e5961906d942ab0efa9e1d9 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: