diff --git a/README.md b/README.md
index ec5ffc997..652162888 100644
--- a/README.md
+++ b/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 (example [1](https://github.com/lsegal/yard/issues/1410) [2](https://github.com/lsegal/yard/issues/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