Using Redcarpet for Markdown in Slim

Suraj N. Kurapati

  1. Problem
    1. Solution
      1. 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:

        1. Render options
        2. Markdown extensions

        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'