Custom Markdown in Middleman

Thu, 17 Nov 2016 00:00:00 +0000

Middleman is an excellent static site generator written in Ruby. It is extremely practical for blogging as well, and it's the framework I am currently using for this blog.

Unfortunately Middleman's documentation is a bit unorganized and incomplete. I often find myself browsing through the source code to understand how to use or implement some custom features.

For example, using redcarpet I wanted to be able to create some re-usable “markdown components” that I could use in my blog posts. Something like bootstrap alerts, so that I could re-use them without having to add HTML or any code to my markdown.

And this post I am going to explain how to integrate this functionality into your blog using Middleman.

Creating a Custom Renderer

Middleman comes built in with a custom Redcarpet renderer which Middleman uses to parse the links and images (and possibly other things) in your blog's markdown. To be able to implement our custom markdown we need to create our own custom renderer, which should inherit from Redcarpet::Render::HTML. However, the key thing here is to actually inherit directly from Middleman's renderer (which of course, inherits from Redcarpet::Render::HTML).

To begin, we will create a lib (if it doesn't exist) under our blog's directory and create a file named markdown_helper.rb inside it. The initial contents of this helper will be:

module MarkdownHelper

  require 'middleman-core/renderers/redcarpet'

end

The required file above is what will allow us to inherit from Middleman's renderer.

middleman on Andrés Álvarez

Custom Markdown in Middleman

Creating a Custom Renderer