The Kitchin Research Group

A few people have asked me about how I generate the posts in this blog, so I thought I would try to capture that process here. The blog itself is generated by blogofile ¹. Blogofile is a pure python, static blog generator. I will discuss the setup of that another time. Here I will focus on how the posts are written and published to the blog.

The posts in this blog were created using Emacs and org-mode ². Basically I create a heading in org-mode (any level will do, but I usually make them top headings, i.e. with one *). The post can contain all the markup in org-mode that can be exported to HTML, including equations, code, links, and images. I set org-properties of the heading for the categories and tags of the post.

Blogofile wants a post to be a file in a specific directory called _posts . The file must have a YAML heading, followed by the body of the html that will be the post. So, to create a blogofile post, we have to export the org-mode heading to a properly formatted post file, in the _posts directory of the blogofile root. org-mode has an excellent export system for generating html, but I had to write some customized emacs-lisp code to get exactly what I want. That code is available at https://github.com/jkitchin/jmax/blob/prelude/blogofile.el. I am sure this code is not written most elegantly, but it has worked for me for about 186 posts (counting this one). This file gets loaded in my init.el file. It is very likely you will have to run a fairly modern version of org-mode (at least 8+) to do this. You will also probably need to configure your org-mode like mine to get similar looking results. My current setup builds off of Prelude³. The contents of the personal directory can be found here https://github.com/jkitchin/jmax/tree/prelude. I keep a git version of org in there.

Basically the blogofile code does the following:

1. Grabs the content of the current org-mode heading
2. Constructs the YAML heading from information in properties of the heading, and the heading title
3. Exports the heading body into an HTML string. If your post has images in it, there is an additional step required. In blogofile.el, I temporarily redefined org-html–format-image so that it would copy the image to the images directory in the blogofile root, and return a url that would be correct when it is published to github. My blog uses Mathjax, so equations are automatically handled correctly.
4. Combine the YAML heading and HTML string and save it to a file in the _posts directory.
5. Enter a few new or update properties in the heading about when it was created and/or updated
6. I wanted the org-code for each post to be published on the blog so I also save the org-code to a directory in the blogofile root and add a link to it in the HTML file.

All of that action is written in a single command called bf-blogpost which I bind to the F10 key. So, after I am done with my blogpost, I press F10, and the post is created in my blogofile root directory. I find that pretty convenient.

To publish it to github, I have to do the following:

1. Change into the blogofile root directory, and run "blogofile build" which generates the html files from the new _post. I can locally serve the blog to check out the post if I want.
2. Copy the new files to a directory called _deploy, which is is the master branch of the repository at https://github.com/jkitchin/jkitchin.github.com, and only contains the published blog HTML
3. Commit the new changes to the repository and push them to github. A few minutes later, the new post is visible on the website, which is hosted by GitHUB (Thanks GitHUB!).

This all works well on my windows machines. I don't know why, but I cannot build the blog on a Linux machine. Maybe because of mixed dos/unix line endings, or something silly like that.

After spending some time getting this workflow to work, I find it pretty convenient. I love that I can write the posts in org-mode, because most of them are about using python or emacs-lisp, and I like to have the code and output together with my narrative text. I also like that the actual org-code is available as a link in each post. That way if I don't remember how I did something I can always go back to the source, or my students can learn how I used org-mode.

One thing I have not figured out yet is how to have uploads, e.g. if I use a datafile in a post, it would be nice to have the blogpost function automatically copy that file to the right place so that the link to it works in the blog. I haven't needed that too often, so it has not been a high priority.

Copyright (C) 2013 by John Kitchin. See the License for information about copying.

org-mode source