From 88612bf7cef0d41aa3be9f17dcfc6554e67d7725 Mon Sep 17 00:00:00 2001
From: Parker Moore <parkrmoore@gmail.com>
Date: Thu, 26 Dec 2013 00:52:20 -0500
Subject: [PATCH] Add docs for custom markdown processors.

---
 site/docs/extras.md | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/site/docs/extras.md b/site/docs/extras.md
index 0c190ec1..14261e34 100644
--- a/site/docs/extras.md
+++ b/site/docs/extras.md
@@ -16,7 +16,12 @@ Maruku comes with optional support for LaTeX to PNG rendering via blahtex
 Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku
 fork](http://github.com/remi/maruku).
 
-## RDiscount
+## Alternative Markdown Processors
+
+While Jekyll defaults to using Maruku for Markdown conversion, you may use one
+of the other three pre-defined markdown parsers or define your own.
+
+### RDiscount
 
 If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead
 of [Maruku](http://github.com/bhollis/maruku) for Markdown, just make sure you have
@@ -34,7 +39,7 @@ have Jekyll run with that option.
 markdown: rdiscount
 {% endhighlight %}
 
-## Kramdown
+### Kramdown
 
 You can also use [Kramdown](http://kramdown.rubyforge.org/) instead of Maruku
 for Markdown. Make sure that Kramdown is installed:
@@ -54,3 +59,34 @@ Kramdown has various options for customizing the HTML output. The
 [Configuration](/docs/configuration/) page lists the default options used by
 Jekyll. A complete list of options is also available on the [Kramdown
 website](http://kramdown.rubyforge.org/options.html).
+
+### User-Defined
+
+So, you're totally at odds with our four built-in markdown parsers, eh? No
+sweat. You can define one as a plugin:
+
+{% highlight ruby %}
+require 'jekyll'
+require 'some_renderer'
+
+class Jekyll::Converters::Markdown::MyCustomParser
+  def initialize(config)
+    @site_config = config
+  end
+
+  def convert(content)
+    # (this _must_ return the resulting String after the rendering)
+    SomeRenderer.new(@site_config).to_html(content)
+  end
+end
+{% endhighlight %}
+
+Once you've got that setup, ask Jekyll to use your custom markdown parser in
+your `_config.yml` file:
+
+{% highlight yaml %}
+markdown: MyCustomParser
+{% endhighlight %}
+
+(Note that this **is case-sensitive**, and is only the piece after
+`Jekyll::Converters::Markdown`.) And there you are!