Merge pull request #37 from seanmadsen/master

Admonitions and other improvements to markdown documentation

README.md

-# 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

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.

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
 

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: