documentation about markdown providers

closes lsegal#1410
closes lsegal#1543

README.md

@@ -122,6 +122,13 @@ HTML. If running `which rdoc` turns up empty, install RDoc by issuing:
 $ sudo apt-get install rdoc
 ```
 
+### Markdown parser
+
+When rendering markdown, yard will use one of several possible markdown providers,
+[in order of priority](https://github.com/lsegal/yard/blob/e833aac7a01510245dd4ae1d1d18b046c8293c2d/lib/yard/templates/helpers/markup_helper.rb#L26-L33).
+If you are experiencing rendering bugs (#1410, #1543), try adding one of the
+gems further up in the list to your Gemfile.
+
 ## Usage
 
 There are a couple of ways to use YARD. The first is via command-line, and the