Rails + Markdown + Syntax Highlighting

This post is to help you add syntax highlighting to your markdown in a rails app. I prefer to use Redcarpet for markdown processing, and Rouge for syntax highlighting. This is a complete ruby solution, I believe its the fastest, and somewhat easy to implement.

Steps

  1. Add the redcarpet gem.

  2. Build a MarkdownParser class to handle parsing our markdown.

  3. Add the rouge-rails gem.

  4. Build a RougeRenderer class to handle syntax highlighting.

  5. Use the RougeRenderer class as the Redcarpet mardown renderer.

  6. Set up your styleheets.

  7. Display the parsed markdown with syntax highlighting in code blocks

Add the redcarpet Gem

# Gemfile

gem "redcarpet"

MarkdownParser Class

# app/models/markdown_parser.rb

class MarkdownParser
  require "redcarpet"

  def initialize(markdown)
    @markdown = markdown
  end

  def markdown_to_html
    processor.render(@markdown).html_safe
  end

  def processor
    Redcarpet::Markdown.new(renderer, extensions = {})
  end

  def renderer
    Redcarpet::Render::HTML
  end
end

Add the rouge-rails Gem

# Gemfile

gem "rouge-rails"

RougeRenderer Class

# app/models/rouge_renderer.rb

class RougeRenderer < Redcarpet::Render::HTML
  require "rouge"
  require "rouge/plugins/redcarpet"

  include Rouge::Plugins::Redcarpet
end

Use RougeRenderer As Redcarpet Renderer

# app/models/markdown_parser.rb

class MarkdownParser

  ...

  def renderer
    RougeRenderer.new(render_options = {})
  end
end

Styelsheets

There are a couple of ways to add the code styles to you rails app. I like to use the rouge rougify CLI command to generate a stylesheet. The CLI command should let you generate any theme found in the rouge gem's themes.

For example, to generate a github stylesheet:

$ rougify style github > app/assets/stylesheets/github.css

Then add it to your application.scss file.

# app/assets/stylesheets/application.scss

@import "github";

You can also copy a stylesheet from here, but be aware of how the classes are scoped. You will have to set up Rogue to handle themes.

Use it

Pass the markdown parser a file:

<%- file = File.read("path/to/file.md") %>
<%= MarkdownParser.new(file).markdown_to_html %>

Pass the markdown parser text:

<%= MarkdownParser.new("#heading ```code {} ```").markdown_to_html %>

Resources: