This is my first blogging experience.
I just got more interested in producing one because I realized I could do it by pushing commit-posts to GitHub.
Enter Octopress. A simple google search for blogging by GitHub Pages brought me to it.
In this post I’ll talk about my setup and how I got Octopress configured for a good programming and math blog. And how I ended up learning a bunch of stuff about Ruby and Markdown.

The tools

Octopress acquired fame as a “hacker” blogging platform compared to alternatives like WordPress, and indeed it is and just what I had been looking for. So I’m,

• using Octopress
• using RVM as my Ruby Version Manager, and the RVM GUI, JewelryBox
• using POW as the local web server for previewing before commiting/posting
• using Mac with OS X Lion
• using GitHub Pages to host my site and blog (for free)
• using point DNS HOSTING for DNS management of my personal domain (for free)
• So, to host the blog on my personal domain I’m paying only for the domain registry ($15/year)
• using VIM as my editor of choice ( full-screen ;-) )
• using kramdown as the Markdown parser (more details below)
• using MathJax and kramdown to display math through $\rm \LaTeX$
• using kramdown’s choice for syntax highlighting of code snippets: CodeRay

Initial difficulties

First of, I wasn’t well familiarized with git before starting the blog. I’ve messed things up following the Octopress tutorial, learned from that, and now I see how neat git is. I was amazed by the logical separation of concerns for the actions you can take when thinking about VCS.

After learning how to use git more properly I’ve started again by forking the Octopress repository and followed Oren K’s workaround on how do not get my archives directory in a /blog/blog/ url and also changed my permanent link in the _config.yml configuration file to avoid this too in permanent urls.

My second difficulty was with the use of RVM, a Ruby Version Manager.
Octopress expects you to work in a Ruby version managed environment so that it don’t get in trouble with different versions of Ruby. I’m also using JewelryBox for OS X, a RVM GUI.
While dealing with the RVM/JewelryBox installation I got my user .bashrc file cleared. I don’t know how it happened, but it was one of these two, so, by now, I advice you to back it up before installation.
Then I’ve spent a while figuring out why JewelryBox, and more precisely, RVM, were not working. The installation writes a script line at the end of the .bashrc but it wasn’t making any effect to change the Ruby version when needed. Alas, RVM needs the same config it writes to .bashrc in the .bash_login file on Mac, which was inexistent, I’ve created one as a symbolic link to my .bashrc and finally RVM was setup and it’s indeed good at managing Rubies without need to overwrite the system one.

Difficulties with math display using MathJax and $\rm \LaTeX$

So, I was with everything ready to make my first commit-post, RVM was nicely changing the working Ruby version when I executed cd <local Octopress repository>, everything was setup for Octopress and my VIM environment was nice (also, I started using MacVim and the Pathogen plugin and it got even nicer), so I thought of testing math display by using MathJax.

First, it was trivial to get $\rm \LaTeX$ input working reasonably well with the stock Octopress following Gregory A. Lussier’s tutorial. There was a little MathJax issue when an equation got right-clicked but it was easily solved following Steven Shaw’s advice. But, in the end, there’s was one caveat yet: no matter how I tried, I was not succeeding at displaying an inline equation by using $\rm \LaTeX$ inside a paragraph containing Markdown. I had gone deep to realize there was a fundamental limitation in the Octopress default Markdown parser: Ryan Tomayko’s RDiscount, in Ruby, which is based on David Loren’s Discount C parser.

A Markdown parser basically follows John Gruber’s guidelines and syntax with possible extensions to it. And the limitation of not being able to get $\rm \LaTeX$ syntax lying in the same paragraph as other Markdown content was due to the parser. Discount, and by consequence RDiscount, don’t support any extension to inform the parser to stop parsing Markdown inside a paragraph, so that we can input $\rm \LaTeX$ without it being parsed as Markdown.

No problem!, the backbone of Octopress is Jekyll (so, Octopress $\rightarrow$ Jekyll $\rightarrow$ RDiscount $\rightarrow$ Discount), which supports multiple parsers (at first I thought of creating a patch for Discount…).
I was adviced to change from RDiscount to Redcarpet because it had some <nomarkdown> functionality but it was a mistake, it hadn’t. By the way, Redcarpet is built on top of the Sundown library in C, which is a fork of the Upskirt library by Natacha Porté, now renamed to libsoldout. Redcarpet is used on the GitHub Flavored Markdown to render Markdown on GitHub. Anyway, I’d need to apply a patch to Sundown to get my inline $\rm \LaTeX$, and also, by now, Redcarpet 2 is not supported out of the box by Octopress. I’d gone through a hard time to figure out I needed to put the dependency to Redcarpet 2 at the Octopress’s Gemfile file, even it being installed on the correct Ruby version. Without this Octopress just got lost trying to reference other stuff while generating a post. So, anytime you install a gem to be used by Octopress I advice you to take a look whether it also needs to be put in the Gemfile and then, rerun bundle install.
I got other problems with Redcarpet 2.1.1 on Octopress, trying to use fenced code blocks for code highlighting just rendered my post output blank. I’d given up on Redcarpet although I think it could be used without the fenced code block feature. I was able to use inline equations with it using the MathJax \\( latex equation \\) syntax and code highlighting could be done through the Inline Code Blocks plugin syntax.

With a bit of luck, I’ve found by accident at my Octopress’s Gemfile.lock file (it’s a file created by the Bundler dependency manager for Ruby) that Jekyll was depending of a unknown (by me) Markdown parser, kramdown. So I had take a look a this parser to see whether it was actively supported, and indeed it is. Differently from the other parsers, this one is not built on top of a C library, and still, tries to be fast enough. But what has pleased me more was to know it actively supported $\rm \LaTeX$ and MathJax out of the box.

So I changed the parser to kramdown

The easiest path to seamlessly adopt kramdown on Octopress is resumed to some few CSS tweaks (in truth Sass tweaks) I’ve done in one single commit. I’m using the original CodeRay CSS file as input to compass as used by Octopress.

With this I can use both kramdown to output highlighted code like the following Markdown:

{:lang="ruby"}
    def fact(n)
      if n == 0
        1
      else
        n * fact(n-1)
      end
    end

which gives me this highlighted output:

def fact(n)
  if n == 0
    1
  else
    n * fact(n-1)
  end
end

or Octopress’s built-in Pygments support to output the following:

{% codeblock lang:ruby %}
def fact(n)
  if n == 0
    1
  else
    n * fact(n-1)
  end
end
{% endcodeblock %}

like this:

1
2
3
4
5
6
7

def fact(n)
  if n == 0
    1
  else
    n * fact(n-1)
  end
end

By using kramdown, Octopress’s Backtick Code Blocks syntax was not a option anymore.
For gists and other stuff beyond in-place code my only option is the default Pygments, for example, this:

{% gist 3064093 clojonacci.clj %}

gives me this:

For inline code samples I’m using kramdown’s backquotes syntax like this `std::cout << "Hello World";`{:lang="c++"} which gives me this std::cout << "Hello World";.

and finally with kramdown, I’m able to both input $\rm \LaTeX$ for displaying like this:

1

$$R_{ab} - {\textstyle 1 \over 2}R\,g_{ab} + \Lambda\ g_{ab} = \kappa\, T_{ab}$$

which gives me this:

as also I’m able to input inline math $($like $e^{i\tau}=1$$)$ using the same syntax.

Resuming

The end result of all this boils down to forking Octopress, installing kramdown (also adding it as a dependency in the Gemfile and running bundle install) and doing a few tweaks.
It was a nice trip and I’m enjoying my new blogging environment: