Using Redcarpet for Markdown in Slim

Suraj N. Kurapati

10 October 2013

Problem
Solution
Example

The Slim template language lets you embed Markdown sub-templates and its underlying Tilt template processing engine lets you use your favorite Markdown implementation in Ruby to process them.

I prefer the Redcarpet implementation of Markdown in Ruby because I have personally worked with it before to convert Markdown documents into UNIX manual pages.

Problem

Tilt assumes that Markdown implementations only accept one set of configuration options, whereas Redcarpet accepts two of them:

When you tell Tilt to use Redcarpet for rendering Markdown, it only passes your configuration options as Markdown extensions to Redcarpet. Thus we have no standard way of passing render options to Redcarpet through Tilt.

Solution

We can work around this limitation by passing a pre-configured renderer (which is already configured with our desired render options) as part of the Markdown extensions for Redcarpet. For example:

renderer_class = Redcarpet::Render::HTML
render_options = {} # TODO: fill this in!
renderer = renderer_class.new(render_options)

Slim::Embedded.set_default_options :markdown => {
  :renderer => renderer
}

Example

Here is a complete, working example to help you get started:

require 'slim'
require 'tilt'
require 'redcarpet'

renderer_class = Redcarpet::Render::HTML
render_options = {
  # https://github.com/vmg/redcarpet#darling-i-packed-you-a-couple-renderers-for-lunch
  :filter_html     => false,
  :no_images       => false,
  :no_links        => false,
  :no_styles       => false,
  :safe_links_only => false,
  :with_toc_data   => false,
  :hard_wrap       => false,
  :xhtml           => false,
  :prettify        => false,
  :link_attributes => {},
}
renderer = renderer_class.new(render_options)

markdown_extensions = {
  # https://github.com/vmg/redcarpet#and-its-like-really-simple-to-use
  :no_intra_emphasis            => false,
  :tables                       => false,
  :fenced_code_blocks           => false,
  :autolink                     => false,
  :disable_indented_code_blocks => false,
  :strikethrough                => false,
  :lax_spacing                  => false,
  :space_after_headers          => false,
  :superscript                  => false,
  :underline                    => false,
  :highlight                    => false,
  :quote                        => false,
  :footnotes                    => false,
  :renderer                     => renderer
}

# https://github.com/slim-template/slim/issues/245#issuecomment-8833818
Slim::Embedded.set_default_options :markdown => markdown_extensions
Tilt.register Tilt::RedcarpetTemplate::Redcarpet2, 'markdown', 'mkd', 'md'
Tilt.prefer Tilt::RedcarpetTemplate::Redcarpet2, 'markdown'