diff --git a/plugins/markdown.md b/plugins/markdown.md
index 9f8e505e..ef97f4e3 100644
--- a/plugins/markdown.md
+++ b/plugins/markdown.md
@@ -59,10 +59,16 @@ The `githubRepoName` and `githubRepoOwner` indicate which GitHub repo should be
 
         "markdown": {
             "parser": "gfm",
-            "dialect": "Maruku"
+            "hardwrap": true
         }
     }
 
+### Why two parsers?
+
+The "evilstreak" parser is flexible, extensible, currently-maintained, and was the only parser available in earlier versions of the Markdown plugin, but doesn't support the useful GFM extensions.  The "gfm" parser is based on the no-longer-maintained Showdown parser, but is the actual library used for GitHub's [client-side previews](http://github.github.com/github-flavored-markdown/preview.html).
+
+In the future, if GFM support is made available for the "evilstreak" parser, this plugin will drop the "gfm" parser in favor of that support.
+
 ## Extended tag support
 
 While the Markdown plugin already supports JSDoc's default tags, if you're using other plugins, you may well have extra tags available.  You can tell the Markdown plugin to handle those extra tags as well using the `tags` property, which is an array of the tags* it should check in addition to the default set.