As you maybe have read in the first article about how I chose to process input (for now still only me, but in the future other users as well as I build up the commenting), you’ll know that after working with a couple options and a little research I chose to use the Redcarpet gem for processing markdown used to write the article ‘body’ (which is what you’re reading right now).

Since, I installed that gem, I have been lamenting the lack of some functionality. This functionality, I thought, would have to be custom built by me at some point when I was brave enough to focus on extending the built in Redcarpet functionality as you can do rather easily (in principle) according to the documentation provided on the repository where the code is stored. The two main issues I was having with the default functionality was that i couldn’t add any additional formatting to links to make them open in a new window (or tab) as I often like to do, and I couldn’t get code blocks to function properly. I thought I would have to write code (or implement another gem named Pygment) to get these two things done. It was bugging me because the option I passed on, kramdown did have a way to easily add target="_blank" to links that I learned about while writing a draft article for a jekyll based blog that one of my meetups is trying to get going. (At this time, April 7th, 2016, the draft has not yet been approved for publication). Though slightly annoying, this built-in functionality was not enough to overcome my previous concerns, so I left Redcarpet in place and put off the pressing issues until I had time (and confidence to build them). As it turns out, I needed neither time nor confidence.

I’ve read in more than one place that one of the signs of a ‘good’ open source project is a thorough documentation. Now, some projects have websites devoted to their documentation which can be awesome and some projects just use the repository itself to list a good guide to not only start using them but to provide you with the built-in capabilities and how to expand on them, if possible. Redcarpet falls into the latter category. Some of the documentation requires a better understanding of Object-Oriented Programming than I currently have, but I can tell that the documentation is well explained and spelled out. And, as it turns out, those two things that were ‘future projects’ could easily be implemented, from Redcarpet itself, if only I had paid better attention and been more thorough when I first started using it.

Now, you might be wondering to your self, “Self, why did our intrepid blogger both bold and italicize that phrase above?”. Good question, dear reader. The answer, both simple and embarrassing, is this. I highlighted that phrase because it is too often the cause of frustration or initial failure in my learning processes. Be it programming, cooking, learning to use a new piece of complex machinery, too often have I read ‘some’ and then jumped ahead to think I had it all figured out, and that’s what happened when I started using Redcarpet.

Instead of thoroughly reading the documentation all the way through, I just followed the basic instructions for getting started. Instead of reading further, I proceeded to search StackOverflow and when I found the answer that solved my immediate problem, I built a quick tinyapp to see what would happen. When the tinyapp was successful, I just went about implementing the gem into my article as I spelled out earlier. And, while I glanced through the various built in attributes and methods to this very useful tool, I did not pay close enough attention to their names and descriptions or I would have seen that Redcarpet does come with the built-in ability to do exactly what I had been saying it couldn’t do (out loud, to people, who program, so that’s pretty embarrassing) out of the box, if one only pays attention and is thorough (see - there it is again).

At some point today (April 7, 2016 for those of you who forgot earlier), for reasons I don’t really remember, I was again looking at the Redcarpet repository. This time, however, as I scrolled down, I paid slightly more attention and a few built-in abilities caught my eye:

  • :fenced_code_blocks
  • :disable_indented_code_blocks
  • :link_attributes

Now, I won’t bore you with the gory, and of course very embarrassing, details, but suffice it to say, as I read what these three built-in tools did, I realized that they most likely would solve my problem, if I could implement them properly. I’d like to say that I could go back into the tinyapp I built earlier, but, after a quick search, it seems I deleted it for some reason, so I was just going to have to test it on the source code for this blog resident on my home computer, which while not the end of the world, isn’t ideal or as easy.

Solving the Code Block Issue

If you’ve ever read any blogs from coders, you’ll have seen well formatted code blocks to give examples of methods, function, class definitions, etc…as part of their articles. I knew from learning about jekyll that you could ‘surround’ a code block with three of these - ` and you could easily display a code block. Using one of those symbols is how you get the code you see here puts "hello". However, if you try and write multiple lines of code surrounded by only the single `, it won’t work, and the three in a row thing isn’t built in. (Trust me, I’ve tried, and if you have read article from me before this date, you’ll have seen some lame attempts at including code blocks). There are some rather clunky built-in methods involving the number of spaces at the beginning of your line, but it’s easier if you can just do the surround method. After properly reading the documentation I had previously ignored, it seemed like the first two of the three methods listed above would work, so I went about sliding them into the code. In that first article, there is a method listed (using the clunky method) that sets up the markdown processing. The only option passed is filter_html: true. To implement the code block functionality I need, it should be as simple as adding fenced_code_blocks: true, disabled_indented_code_blocks: true after the filter_html statement. So off I went to try it.

(5 Minutes later)

It worked, and it was that simple, but it still took me two tries to do it because if you read the documentation you notice the code block functions and link attribute functions actually go in different places, and I put the code block ones in the wrong place to start. They do not go after filter_html: true which is part of the renderer definition. They go with the new Markdown call, which uses the renderer. The Markdown call and renderer each have their own built-in helpers, thus the separation in the documentation. I just moved a bit too fast (as usual) and got it mixed up. However, after getting the in the right place, I did a little fiddling with my ‘at home’ version of this and discovered that the old code block indentation (which I did use a few times and will have to find) stopped working but the three ` code block indicator was working. (Now, highlighting the code requires something different, the most popular one seems to be Pygment but that’s for later.) Now, let’s deal with that pesky link issue.

One thing that always bugs me is when a link on a page I’m reading opens in the same window. It’s a link in the middle of what I’m reading, what if I want to just save it for later, and keep reading what I’m in the middle of. Personally, I think if you write your code with links that leave your site in the same window, that’s just a mistake. Fortunately, there’s a pretty basic tool in HTML (which, in the end, displays the web pages you’re reading) that allows you to set up links to open in new windows (or tabs, if the users browser is set up properly, and tabs are freaking awesome). target="_blank" added to the link definition will do the job. (I don’t know if the leading _ is necessary, but it’s how I learned it it in the olden days, so I’ll just stick with it for now.) Markdown, as defined by the folks here doesn’t not allow any kind of additions to basic link writing. So I thought I was out of luck for the time being. The links on my site would be annoying and take you away from my site even if I didn’t want them to until I could figure out how to write the code to properly allow that. As we know now, I didn’t really need to write anything, I just needed to pay attention. So, making this work should be as simple as above, and hopefully only one try because now I know where to put the statement.

(5 minutes later)

So that took longer than it probably should have, and sadly, for the same reason it usually does. I didn’t fully read the documentation. link_attributes takes a hash of attributes that will be applied to all links on the site. A hat tip to StackOverflow for a related question pointing that out to me. Now, this isn’t ideal, because as people navigate through my site, they will open new tabs (or windows) and that will be annoying to them, but for now, it’s a working solution until I get something more nuanced that allows me to control the attributes on specific links. It will probably involve that Liquid gem I haven’t gotten to yet. So after adding link_attributes: {target: "_blank"} in the right place, the link in my test article at home opened a new link. (Links in this article will open in new windows/tabs as well)

So, that’s that. Instead of having to struggle my way through writing custom code, a chance web search leads me back to read the documentation that I had not paid close attention to before, and both of my pressing issues are, to a point, solved. Sure, they aren’t perfect yet (the code doesn’t highlight like in an editor, and all links open new windows) but it’s better than it was before and it took me under two hours to get it done. At this point, if I attempted to write custom code to solve these issues, I don’t know how long it would take me or if I’d ever successfully make them both work.

So a simple GACP (with two pushes, one to my repository and one to heroku) and the live app now has the desired changes for links and code blocks (and I’m off to alter the few code blocks I tried to write in earlier articles, and drafts, to fit the new guidelines).

So folks, the moral of the story is, of course, this: Always read all the instructions.

Until next time.