How to Render Markdown Views in Rails

For a personal project, I wanted to render markdown files in my Rails views. Not fetching and rendering markdown from the database, but rendering the plain markdown files under the views directory.

At first, I thought it would be complicated, involving searching for views, parsing the markdown content, and rendering it. But a little Google search revealed that Rails already supports this functionality, with a few lines of configuration. This also lets you render them as partials within other views.

Let's see how to accomplish this in two simple steps.

Step 1: Add a Handler to Convert Markdown into HTML

Let's add a new class called MarkdownHandler which converts markdown content to HTML using the Redcarpet gem. We'll store it in a handlers directory in the lib folder.

# lib/handlers/markdown_handler.rb

module Handlers
  class MarkdownHandler
    def call(template, source)
      markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML)
  
      "#{markdown.render(source).inspect}.html_safe"
    end
  end
end

The call method receives the template file which represents our views and the source, which is the markdown content. Then we convert it to HTML and return the generated HTML string.

Step 2: Register the Markdown Handler

Next, create a new initializer called markdown.rb under the config/initializers directory. An initializer is simply a piece of Ruby code that runs at the start to configure your Rails application or external gems.

To learn more about Rails initializers, check out the following article:

All our initializer does is register the markdown handler class we just created to handle any markdown templates, i.e. markdown files with the .md extension.

# config/initializers/markdown.rb

require 'handlers/markdown_handler'

ActionView::Template.register_template_handler :md, Handlers::MarkdownHandler.new

The register_template_handler method registers an object that knows how to handle template files with the given extensions. This can be used to implement new template types.

The handler object must respond to call, which will be passed the template with its content, and should return the rendered template as a String.

And that's it. We're done!

To use this, simply create new markdown files in the views directory. Don't forget to use the extension .html.md so Rails renders the resulting text as HTML. If you want to separate the static content from your application, just prepend the content directory to the views path, as follows:

# app/controllers/application_controller.rb

class ApplicationController < ActionController::Base
  append_view_path "content"
end

Now you can put the static markdown pages in the content directory, outside the app directory.

In a future post, we'll inspect how the register_template_handler is implemented along with the rest of the view functionality in Rails. Meanwhile, if you have any questions or feedback, didn't understand something, or found a mistake, please leave a comment below or send me an email as always.

I look forward to hearing from you.