How to add markdown support to Ruby on Rails

I was recently asked to give an overview of how to add markdown support to a Ruby on Rails application. This guide will leverage a gem called Redcarpet to help us do just that.

I use markdown for virtually any work I do. I actually wrote then entire Hello Rails course in markdown. This blog's post editor is based in markdown as well. It's safe to say I love it over any other type of word editor out there. Adding support for it in a Ruby on Rails app is quite trivial thanks to a few gems out there. I'll be leveraging the Redcarpet gem in this guide.

Initial setup

Kicking things off, you first need to create a fresh Ruby on Rails app or modify an existing to include the Redcarpet gem.

# Gemfile
gem "redcarpet"

With that installed, run:

$ bundle install

Generating a resource

For this guide, I'm assuming you created a fresh Rails app without much data to work with yet. We'll need a resource to add markdown support to. The quickest route to doing that effectively is using a scaffold generator that ships with Rails.

$ rails generate scaffold Post title:string body:text

As a generic example, I'll create a Post scaffold to work with.

Extracting logic to a helper

With the Redcarpet gem installed there's only a little more groundwork to cover to get markdown to render as HTML on the frontend. In efforts to be DRY (don't repeat yourself), we can leverage a helper method to render markdown as HTML accordingly.

Since we may use this helper across all areas of the app I'll add the following code to application_helper.rb.

# app/helpers/application_helper.rb

module ApplicationHelper
  def markdown(text)
    options = [:hard_wrap, :autolink, :no_intra_emphasis, :fenced_code_blocks]
    Markdown.new(text, *options).to_html.html_safe
  end
end

This method titled markdown will be useable in our views. It takes a text argument which will ultimately be the output of our Post body field. Notice the options variable defined with an array of settings you can pass to Redcarpet. These dictate what you do and don't want when it comes to rendering markdown within your app. Be sure to check out the documentation for a longer list of various options you can add.

We'll leverage the Markdown class and create a new instance passing in our text argument and options. The .to_html probably is a no brainer but that essentially calls a method to render HTML output from the instance. Tack on a html_safe method for bypassing the built-in security of rendering HTML.

The screencast goes into greater detail of how this all works as well as setting things up. In the end, you can now leverage this helper in your views app-wide.

My Post show view might look like this for example:

<p>
  <strong>Title:</strong>
  <%= @post.title %>
</p>

<p>
  <strong>Body:</strong>
  <%= markdown(@post.body) %>
</p>

<%= link_to 'Edit', edit_post_path(@post) %> |
<%= link_to 'Back', posts_path %>

Note the new helper method wrapping @post.body. This should be all we need to get HTML to output successfully. Pretty simple!

Shameless plug time

I have a new course called Hello Rails. Hello Rails is a modern course designed to help you start using and understanding Ruby on Rails fast. If you're a novice when it comes to Ruby or Ruby on Rails I invite you to check out the site. The course will be much like these builds but a super more in-depth version with more realistic goals and deliverables. Download your copy today!!

Follow @hello_rails and myself @justalever on Twitter.