If you read my first article (here), you’ll have noticed that it was rather primitive in terms of layout and styling. As I stated then, there was a method to the madness (or primitiveness if you will) of what I was doing here.

As such, my first article was written with plain old regular HTML and the lovely Rails method helper simple_format was used to process to body attribute of my article instance. This isn’t the best way to do this for a a few reasons not the least of which are:

  • It’s annoying to have to write opening and closing tags all the time
  • simple_format will not process any kind of dynamic code using ERB or anything similar

At some point, for some reason, while I was on one of my many breaks, the concept of simpler markup (the M in HTML stands for Markup if you weren’t aware) and markup processors evolved. I don’t know if they were first, or the creator, but the markup syntax I currently use is Daring Fireball.

Markdown provides the user with simpler ways to write the basics of laying out HTML on web pages. It simplifies many things. For instance, the most common HTML tag used is probably the tag. (If you don’t know HTML p stands for paragraph, so it separates blocks of text). This is SO common that creating a new paragraph in markdown is as simple as in your word processing document. Write some text, hit return twice, and you’ve created a new p tag This easily allows you to separate your text.

I won’t delve too much into what Markdown is because of one of two reasons:

  1. You code and therefore know what markup means and specifically what Markdown is.
  2. You don’t code, and don’t want to know anything more than what I’ve already told you.

Ok, so that’s fine and good, we now have a cleaner way of laying out web pages, saving time, and making things easier to read. However, browsers tend to like to read HTML. Thus, whatever markup language (and they come fast and furious, for instance, the moment I took a look at HAML, I was told, oh no, HAML is old news, you have to learn SLIM now. Maybe I will, but for now I’m sticking with Markdown.) you want to use, you have to have a way to process it into HTML.

Fortunately for us, markup processors aplenty exist. Since I came about this from a sideways approach, I had already heard of one markup processor, Kramdown (thank you Jekyll), but when I played around with it myself, I wasn’t as comfortable with it as I wanted to be. So after a visit to the good old ruby toolbox, I built a ‘tinyapp’ to mess around with Redcarpet (more on tinyapps later). Redcarpet is a little bit more mature Ruby Gem that for some reason I had more success using and feel it will be even easier to use when I implement a way to include dynamic ruby code into my article body via Liquid (that’s in the future).

So, what are the steps involved in implement Redcarpet into your Rails app John? I’m glad you asked, or at least are interested enough to read on.

Step One - Put the Gem in your Gemfile and run your bundle or bin/bundle

This is the always the first step when installing a Gem into your application. If this doesn’t make sense to you, it’s ok, unless you build Rails applications. Then, you might have an issue.

Step Two - You’ll get by with a little help(er) from your friends.

Now, you could write the code to convert markdown using Redcarpet anywhere it’s appropriate in your application, but that’s not really DRY now is it? So, instead, we want to write a little piece of code that you can call at anytime, anywhere in your application to process markup. So, using the helpful instructions at the above referenced GitHub for Redcarpet, I wrote a simple method that I slid into app/helpers/application_helper.rb

def process_markdown(input)          
  renderer = Redcarpet::Render::HTML.new(filter_html: true)          
  markdown = Redcarpet::Markdown.new(renderer)          
  markdown.render(input).html_safe          
end

Wow, that’s really neat John, how did you figure that all out? Simple, I read the instructions, and got a little help from an old Railscast. (Raise your hand if you wish Railscasts would come back). Oh, and, by the way, see that neat shading on the code block there? Awesome isn’t it? And as of today, December 13, 2016, it looks even better since I added functionality to make code look like the language it’s written in using coderay

Now, not all of this is required to do basic processing of markup, but the reason I chose it over Kramdown was the ease with which you can do certain things.

In the long term, I do plan to have comments be linked to logged in users and allow limited markup from the users, but, sometimes, users can be naughty, so you have to protect against that. filter_html: true means that the input processed by the method will not process any HTML tags native to the content (in my brief experimentation with Kramdown I couldn’t figure out how to get it to ignore HTML but still process markdown. Perhaps it does but I didn’t find it quickly while I was experimenting). So filter_html isn’t necessary but it’s extremely helpful. If you read more of the Redcarpet documentation you’ll find a lot of other useful options like filter_html.

What about html_safe? Well according to apidock, it’s the simple (and dangerous) way to say the code being passed to it is HTML that can be processed. It’s probably not the best idea for user input, and I’ll have to end up using the sanitize helper later on, but for now, since it’s only my input, it’ll do the job.

Step Three - Rewrite the affected view(s) so that this process_markdown is called when displaying the relevant information.

Right now, as of today (March 8th, 2016), this only applies to the show view of the Article controller, and the display of the body of the Article instance (what you’re reading right now). It’s a simple swap, change simple_format(@article.body) to process_markdown(@article.body)

Step Four - Commit and deploy

Commit your changes to your git repository and push up to your host (hi heroku) and there you go.

A couple notes that some of you might be wondering about, or not, at this time:

  • No, I didn’t write any tests for this, and I probably should, but writing tests (I use RSpec) sometimes is difficult for me. (You should see the struggles I’m going through on the NBA site I’m trying to build and how do you test methodology for scraping data and then populating it all?)
  • If you’re reading this before I change it, the first article will now probably look terrible. Remember, it wasn’t written in markup, just pure HTML, so it has to be edited to be markup proper. I’ll try and do that later. (The first article was updated on March 27th 2016, but I’m leaving this buillet point for posterity, that it took close to three weeks to fix the first one)