Alter Marked's markdown rendering behavior in DocPad

docpad.coffee

#########################################################################
# DO NOT USE THIS CODE, there is a better solution in marked.md (below) #
#########################################################################










# This is part of an ordinary docpad configuration file, please integrate into your own or use a distinct module as described below

# Custom markdown setup
	# Marked docs: https://github.com/chjj/marked/blob/master/README.md#renderer
	
	# We need to access Marked, require the npm module
	marked = require 'marked'
	
	# create a new Renderer instance
	customMarkdownRenderer = new marked.Renderer
	
	# add custom renderers
		# for the list with methods you can add, see https://github.com/chjj/marked/blob/master/README.md#block-level-renderer-methods (and below)
	# f.i. wrap div around images and add caption
	customMarkdownRenderer.image = (href, title, text) ->
				# note I went for a `span` since that doesn't interfere with Marked paragraph wrapping behavior
				# using `div` this happened: `<p></p><div>...</div><p></p>` (empty paragraphs before and after		
		output = 	'<span class="img-wpr">'
						# I should probably escape here...
		output += 		'<img src="' + href + '" alt="' + text + '" title="' + title + '" />'
		output += 		'<div>'
		output += 			text
		output += 		'</div>'
		output += 	'</span>'

# DocPad configuration
docpadConfig =
	plugins:
	# ^ object in which we configure DocPad plugins
		marked:
		# ^ docpad-plugin-marked
			markedOptions:
			# ^ options for npm module marked should be specified here
				# docpad-plugin-marked docs: https://github.com/docpad/docpad-plugin-marked#marked-options (not clear at time of writing, hence this gist)
				# Marked docs: https://github.com/chjj/marked/blob/master/README.md#options-1
				
				renderer: customMarkdownRenderer
				# ^ set variable `customMarkdownRenderer` as Marked renderer (instance of marked.Renderer class)
				
				# even more Marked customisation...

# export the DocPad configuration
module.exports = docpadConfig

# If you want to do things cleaner than I did, you can create a file (wherever you want ;^)) and store your custom renderer in it.
# You can then import it as a npm module like so:
customMarkdownRenderer = require './path/to/custom/markdown/renderer.coffee' # `./file.coffee` if file and config sit in same dir!
# Note that changes in a custom file won't trigger docpad-plugin-livereload! (at least when not placed in `src` structure?)

marked.md

Native custom markdown renderer

After investigating the source of docpad-plugin-marked, it turns out the plugin already supports a method to customise the Marked renderer, albeit undocumented.

Alongside the markedOptions object, which is used to pass configuration to Marked, you can add the markedRenderer object. In this object, you can specify custom renderer methods. (Refer to the official Marked documentation for accepted keys.) The plugin then takes care of the rest (i.e. it creates a custom render instance).

A stripped down docpad.coffee file would look as follows:

docpadConfig =
    plugins:
        marked:
            markedOptions:
                # customize Marked... (https://github.com/chjj/marked#options-1)
            markedRenderer:
                # add custom render methods (https://github.com/chjj/marked#block-level-renderer-methods and https://github.com/chjj/marked#inline-level-renderer-methods)
                    # f.i. wrap a span around images
                image: (href, title, text) ->
                    		output = '<span class="img-wpr">'
					                              # I should probably escape here...
	                            output += '<img src="' + href + '" alt="' + text + '" title="' + title + '" />'
	                            output += '<div>'
	                            output += text
	                            output += '</div>'
	                         output += '</span>'

Note my pervious solution wasn't wrong, but this is just cleaner and easier, thanks to the DocPad team!