Well, I got tired of RBP, which was my custom markup language. Here’re a few reasons why:

  1. It was incredibly verbose. It had parentheses for everything and wasn’t particularly fun.

  2. It lacked some features, such as code blocks and formatting.

  3. The parser wasn’t particularly good, and the fact that I had to backslash-escape parentheses (like \( things in parentheses \)) wasn’t fun. Unfortunately, that was a feature of the syntax, as all the "functions" were wrapped in parentheses. For example, if you wanted to bold something, you’d have to (bold "item").

  4. It also broke sometimes. Instead of focusing on writing blog posts, I was trying to wrangle with my bad parser or adding features.

I want to start writing more blog posts, so I didn’t think that my RBP was helping much. I’ll still keep it and try to maintain it since I might want to use it in the future, but I also wanted to add mainstream markup to this.

Why not Markdown?

If you look at my GitHub profile, you’ll notice that quite a few of my READMEs are in Asciidoc over Markdown. I tend to prefer Asciidoc since it’s easier to remember, it has more features (eg. callouts and those warning/info things). I’d also like to get better at AsciiDoc because of these reasons, so I think my blog is a pretty good way to practice. So I’m using AsciiDoc over Markdown.

How did I implement it?

It was pretty simple to implement AsciiDoc support.

First, I just installed the Asciidoctor gem. Because of the way my blog system works, there’s a Post class that generates some HTML and has some metadata (all as instance variables). So I made a new class AsciiDocPost which provides the same instance variables (and some methods). Then, when the method is called to render al the posts, I made it filter between RBP and AsciiDoc posts by extension and it creates an AsciiDocPost or Post instance for each file accordingly. And then, voilà, I had AsciiDoc support (but not quite)!

Now, there were some challenges. I couldn’t figure out how to set/get metadata from AsciiDoc, but that’s also fairly simple:

:key: value
:key2: value2

and so on. I could use this to set my title/tags/description and whatever else.

Then, in Ruby, you can;

adoc_file = Asciidoctor.load asciidoc_string
puts adoc_file.attr "key"
puts adoc_file.attr "key2"

This should print "value" and "value2." But effectively that’s how I could programatically get metadata from AsciiDoc.

There was also the challenge of CSS, so I wrapped what AsciiDoc outputted in a div so I could handle its CSS overrides (because AsciiDoc sets some custom classes) while still being able to share some of the post styling from RBP.

If you want to see the code for how I did all of this, look at adoc_post.rb, this line in render.rb , and post.scss.

So what’s that code highlighting I see?

I thought syntax highlighting was a good idea, so I added highlightjs. It wasn’t too hard, but I had to add some overrides for Turbolinks and I had to make my CSS font selectors less zealous. It works now, and hopefully it’ll provide a better experience on the blog.