Octopress — adding category tags to the blog RSS feed

Right from the beginning, I’ve assigned broad categories to every post I’ve written here. (For example, this is my—very lacking—Health Monitoring series of posts.) However, Octopress does not include these category tags by default into the RSS feed. So if a reader is using an RSS feed-reader app or website, they cannot make use of the assigned categories even if the app or website was capable of doing so.

I’ve now added some code necessary to add the categories to the RSS feed, and this is what I did.

cellArray = {'Alpha','Beta','Gamma','Delta','GammaSquared'};
refString = 'Gamma';

At the outset, here is the code that I added:

{% for post in site.posts limit: 20 %}
<!-- Other items that are included in the feed -->

{% capture catnum %}{{ post.categories | category_links | size }}{% endcapture %}
{% unless catnum == '0' %}
    {% for cct in post.categories %}
        {% assign idx=forloop.index0 %}<category>{{ post.categories[idx] }}</category>
    {% endfor %}
{% endunless %}

<!-- Other items that are included in the feed -->
<content type="html"><![CDATA[{{ post.content | expand_urls: site.url | cdata_escape }}]]></content>

{% endfor %}

This code works great, but allow me to confess that I am not sure that this is the optimum implementation. To me this seems inelegant, but until I have a better solution, this performs the function appropriately and perfectly adequately.

I’ve only included the relevant portion and the context in which it must be inserted. (See the comment tags <!-- Other items that are included in the feed -->.)

The meat of the algorithm is from lines 7 through 11.

  • A <categories> tag is defined, and a for loop is executed over post.categories, which contains the list of categories for the post.
  • Within the for loop, each post category is enclosed in a <category></category> tag.

Now I had initially thought that the loop variable (cct here) would inherit sequentially the value of each category in post.categories, but apparently that does not work properly. Therefore, the workaround is to

  • identify the loop index (assign idx=forloop.index0) and
  • use individual values of the categories (post.categories[idx]).

We must use forloop.index0 and NOT forloop.index (both are valid commands; the index key starts numbering from 1) because the array numbering starts from 0, not 1.

OK, now that the meat of the algorithm is done, we must put in some code to handle the “unusual” cases—what happens if a post does not have any categories assigned? Such a scenario is handled by the capture command (line 5) and the unless segment that encloses our actual algorithm. The capture command simply captures a value, in our case the number of categories that exist. We only want to include the categories when they exist, therefore our algorithm is run only unless catnum=='0' i.e. when the number of categories is not 0.

Well, that’s it! I have added the code segment before the actual content of each post, but I don’t think it makes any difference if the segment appears after the <content> tag. It should work fine anywhere within the <entry> environment.

☛ Creating “Linked-List” type posts

One of my long-time to-do’s for this blog was to be able to create “linked-list” type posts, where the main heading points, not to a single webpage for the dedicated blog post, but to an external website of interest. (This type of post has been made famous by John Gruber, who is, incidentally, also the creator of the Markdown syntax.)

Well, now I know how to do this (evidence—this post! Ta-da! The title for this post points to The Candler Blog). It turns out it’s not too difficult, but even so, I had help all the way, from The Candler Blog. He has this same implementation, and it turns out, he also has a blog post dedicated to discussing how he did it!

Okay, so, “Daring Fireball-style Linked List posts,” for the uninitiated, refers to the publishing style of John Gruber’s Daring Fireball. For the most thorough explanation of how this works, see Shawn Blanc’s excellent 2009 article, “The Link Post” […]

But how is it done in Octopress? It’s actually very simple. I got a great deal of help, when I was first setting up the site, from Connor Montgomery, who posted his own link post tutorial a few weeks ago. I have since refined the code on my site beyond what we worked out together.

(The Candler Blog website seems otherwise very interesting as well. Go check it out!)

Using MathJax with Octopress

I’ve been meaning to try and implement MathJax on this website for a while now. For including math equations on a website, MathJax is probably one of the more elegant ways to do it. I can write equations in TeX format, and MathJax renders the equations properly for you!

Finally, in the last couple of days I’ve been forced to get around to it, thanks to a new post that I’m writing that includes a little bit of math. So anyway, I just wanted to jot down that process.

The thing with MathJax is that it’s meant to, and does, work with HTML. But since I’m working with Octopress and Markdown, I have to ensure that the conversion from Markdown to HTML produces no unwanted syntactical errors for MathJax. To get around this problem, Zac Harmany (I hope I got the name right) suggests tweaking the Markdown rendering engine to Pandoc, so that the conversion works as desired. I’m sure that works great, but I had no intention of tweaking my Markdown conversion engine. Instead, I discovered a nifty ruby bundle (here) that serves a great purpose.

Next, the typical MathJax “installation” involves adding a line in the <head> section of your Octopress theme (Add it to %octopress_root%/source/_includes/custom/head.html), so that when every page loads, the necessary Javascript files are also loaded, ready to render your equations. I did not want the Javascript to execute to load along with all my pages, given that I don’t expect to have equations in all my posts. Instead, I’ve included the call to the script in the <body> of the post, i.e. in the meat of the post itself. Remember that the declaration needs to be before your first equation.

I also contemplated downloading the MathJax distribution and hosting it locally on my own server, but that did not work at all. There are way too many files to be uploaded (each file is small; the total package is ~50MB; there are too many files, though) and it just took forever to upload to my server until I just gave up. I’ll revisit that option if I think using MathJax’s own servers is not working well—which I doubt will happen.

With those details, here’s how I set things up:

  • Install the verbatim.rb plugin from this Github repository. To do this, simply download the file (‘Gist’ in Github parlance) and place it in %octopress_root%/plugins. When inserting equations, there’s a syntax to using this plugin; I’ll demo it below.

  • Create a MathJaxLocal.js file at %octopress_root%/source/javascripts/ to add local configurations for MathJax. Note that the last line of the code must point to the full path of the local file, in my case http://arnabocean/javascripts/MathJaxLocal.js

    Here’s what my MathJaxLocal.js looks like (I started with Zac Harmany’s file and modified to suit my needs.):

        jax: ["input/TeX","output/HTML-CSS"],
        extensions: ["tex2jax.js","MathMenu.js","MathZoom.js"],
                inlineMath: [ ['$','$'], ['\\(','\\)'] ],
                displayMath: [ ['$$','$$'], ['\\[','\\]'] ],
                skipTags: ["script","noscript","style","textarea","pre","code"],
                processEscapes: true
                equationNumbers: { autoNumber: "AMS" },
                TagSide: "left",
        "HTML-CSS": { availableFonts: ["TeX"] }
  • Declare the location of the MathJax files. The easiest thing to do is to use MathJax’s own servers. However, in addition to just their servers, you’ll have to link to your own local config file as well, so we’ll add both of these at the same time. In the main body of your markdown post (preferably after the “Read More” fold), add the following:

    <script type="text/javascript"

In the above, the first link points to MathJax servers, the second points to my own config file.

And that’s basically it! Now you’re all set to write beautiful equations. Here’s a demo:

<!-- MathJax configuration -->
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML,http://arnabocean.com/javascripts/MathJaxLocal.js">
<!-- End MathJax Configuration -->

{% raw %}{% verbatim tag:p %}{% endraw %}
f(x)= a_0 + a_1\sin(x) + a_2\sin(2x) + ...

+b_1\cos(x) + b_2\cos(2x) + ...

f(x)=a_0+\sum_{k=1}^\infty\big( a_k\cos(kx)+b_k\sin(kx) \big)
{% raw %}{% endverbatim %}{% endraw %}

And here’s what that would look like:

\[ f(x)= a_0 + a_1\sin(x) + a_2\sin(2x) + … \] \[ +b_1\cos(x) + b_2\cos(2x) + … \] \[ f(x)=a_0+\sum_{k=1}^\infty\big( a_k\cos(kx)+b_k\sin(kx) \big) \]

There’s still a lot of more that I need to find out, and from the looks of it, Zac’s website is a great resource. I’ll add more posts if I find anything useful that I end up using.

Website Rebuild — using Octopress

I’d originally designed and built this website in the summer of 2011, and I had made it a point that I myself did all the hard yards of learning the technology and developing (and finding how others had implemented a feature) the HTML and CSS code. I stayed completely away from Javascript, mostly because I basically had no idea about Javascript. I wasn’t sure how resource-hogging Javascript was, and that was a factor, yes—but it was mostly because I didn’t want to use something I didn’t know, and I knew next to nothing about Javascript.

So that was then.

For a while now, though, I’ve been pondering a rewrite and rebuilding of the website, for a number of reasons.

  • The website was not responsive to different screen sizes. It had a certain minimum width that it required, and it always served the same webpage. In today’s world of smartphones and tablets, while it was passable, it wasn’t elegant by any means.

  • As written, it was a pain to make changes to the website. I was dealing with separate HTML pages, and making any changes meant going in manually and make changes to every single page. Tedious, and prone to error.

    I needed a way to make a change once and have it propagate throughout all my HTML pages.

  • I needed to consolidate my writing options. Let me elaborate, and let’s see how convoluted it gets.

    I already have my wordpress blog–GlobeTrekker–which I like and want to continue to maintain—not least because I have certain Google pagerank on there that I don’t want to lose.

    I had started a new blog, a self hosted wordpress blog, on this website, that I had planned would be a “science and technology” blog, separate from ‘everything else’ that I write at GlobeTrekker. But this blog was not the face, so to say, of my website.

    In trying to think of what I could/should write on my “home” page, I decided that I’d use that space to write tutorials about the stuff that I know best about—composite materials, health monitoring, and eventually, even transportation research that I work on at VTTI. I was very excited with this prospect, and managed to write three—count’em, three!—posts, in two years. (There was a reason for this, which I’ll come to.)

    The problem was that I was increasingly finding it inconvenient to write on either of my wordpress blogs. (The reasons for that are for another post altogether.) So I started yet another blog, hosted at Tumblr, that I’ve been using much more productively in the past few months.

    As you can probably start to guess, it was getting tedious and completely inefficient.

  • There was a problem with trying to write tutorial posts (mentioned above) on my home page. The problem was, every time I wrote a new post, there was quite some amount of work neeeded to just post that new material. The previous post had to find a new webpage all to itself. This page had to have links to earlier and later posts. The new homepage had to add new links to the new webpage just created.

    On top of that, every time I did this, Google’s search results went crazy. People searched on Google and found links to my home page, but of course that old content was now at a new webpage. Bad for the person searching, bad for my Google pagerank.

    Tedious, cumbersome, inefficient.

    See a pattern here?

So, in short—I needed some answers. And then recently, and finally, I stumbled upon Octopress.

In short, Octopress is a website building tool. It’s basically a Ruby program that does a number of things right out of the package.

  • Assembles pieces of code to create the required webpages and support files to build an entire website. This straightaway solves my problem of having to make the same changes across all my pages. With Octopress, I make the changes in the one place where I need the change, and Octopress incorporates that change into all the web pages.
  • Creates a blog, which is completely self-contained and self-hosted. Since it assembles everything locally, there’s no need for wordpress-style php pages on the server that handles collating pieces of content to serve a webpage.

    Octopress does it all, once, on my machine, and thereafter it’s just there, available for use.

  • It provides a default theme of its own, but of course I am free to modify the code and designs as much or as little as I want.

    This is excellent, because now I can have all my web pages, including blog pages, with a consistent design. Getting this done with wordpress-hosted blogs is a pain, and while Tumblr is much better with this, it’s still infinitely more convenient to just have to do everything once.

    The website it creates is built to be responsive to different screen sizes. I’d been reading up on @media screen CSS usage, but having this built-in of course helped a lot.

So here we are, with Octopress. What you see now is the result of the redesign and the rebuild. Here’s what has happened:

  • The front page now hosts a blog. This single blog will host the mechanics tutorials that I had mentioned (see here), and also host other pieces that I will hopefully (and am planning to) write.
  • The Tumblr remains the best place to share content that I find interesting on the internet, and I will continue using that, but mostly for sharing with the odd comment. I will try not to write longer pieces on Tumblr. However, I’ll probably cross-post whatever I write on this website on Tumblr, just to reach a wider audience.
  • GlobeTrekker, of course, remains—with the same mission statement. I don’t know how frequently I will write there, though.
  • The self hosted blog will be deprecated. I haven’t removed the files themselves yet, but the posts there have almost all been mirrorred on the new website, and I will remove the old files over time.

So that’s it. New website, new technologies.

And I’ve become much more comfortable with including Javascript on my website since before, now that I’m more confident that I know the basic HTML and CSS technologies well. There are some excellent specialized Javascript tools (such as the brilliant Modernizr and jQuery), that I’d be foolish to not use—and which Octopress, of course, uses out-of-the-box.

How do you like it? There still are improvements to be done, of course—and more of Octopress’s built-in code to be dug into, but that’ll happen over time. I’ve disabled comments for now to make for a cleaner interface, so please use twitter or email to respond.

Welcome to my new website—and happy surfing! :)