Org Mode and Jekyll

Org Mode is major mode in Emacs which provides facilities for managing projects (planning, clocking, tracking tasks, todos and agendas), publishing content in different formats, among which HTML, and working with source code using the literate programming paradigm.

I have been using Org Mode for quite a few years and activities, now. I started using it to manage task, I then experimented with clocking and keeping an agenda, and, more recently I started using it for writing document, where I appreciate the possibility of mixing text and code. This has proved particularly useful, for instance, when I had to write some reports analyzing and discussing data related to food waste. The possibility of playing with code and data while keeping code and descriptions together really made the difference (on top of not having to use copy and paste to include plots generated with R and Gnuplot in a Word document).

Using Org Mode for web publishing my website seemed the natural next step, given the growing sets of assets and experience I have with the tool. However, I never thought Org Mode could match Jekyll’s functions.

When I became more confident with literate programming, however, I realized I could write Org Mode containing code responsible for generating part of the HTML content of the page. Since the result of the computation can be inserted in the page before publishing it, all at sudden I realized I could replicate Jekyll’s “dynamic” facilities by inserting some scripts in the right places.

I thus migrated my website to Org Mode using pandoc, implemented a few scripts which allow me to read YAML files and process pages metadata and went live at the end of February. Six months later, I found myself publishing content more frequently.

Why Org Mode is better:

• Robustness in “degraded” situations. Site building with Jekyll is a all-or-nothing task: if the building process breaks you are stuck till you fix the issue. Publishing a new post requires to build the website, increasing the chances of running into issues related to gem compatibility, errors in your markup, asset bundling, etc, etc. By contrast Org Mode can publish each page individually. There is no need to recompile everything every time. This can make a big difference, since it can help isolate components and content better and even publish “degraded” versions of your website, if you need to.
• Choice in writing scripts Literate programming allow to embed in web pages code written in a variety of programming languages. This code can be used to generate the “dynamic” part of a website, such as the list of posts, sitemaps, plots, etc. You are neither bound to a specific technology, such as Liquid or Emacs lisp. You also have more flexibility in structuring your website. My homepage, for instance, uses a few Ruby scripts to generate the “dynamic” content of my website and with the migration to Org Mode I also moved away from the blog metaphor, structuring my notes more like a Wiki, while, at the same time, presenting a chronological listing of my notes.
• Org Mode markup is simple and robust and feels more natural to me than Markdown. There is, in fact, a Gem that allows to use Org Mode as a markup language for Jekyll websites. However, once you start writing content in Org Mode for a Jekyll website, why not perform the switch to Org Mode altogether?
• Org Mode can publish to different back-ends and, in principle, it makes content reusable in different contexts, such as reports, presentations, web pages. In my case it simplified notes publishing, since I could reuse my “how-to” list, which I already kept in Org Mode.

There are, of course, various things which are performed better with Jekyll. Among them:

• Org Mode has no support for page templates. This is probably the most impacting limitation, because it apparently gives you no control over the HTML generated. When you start digging in the documentation, however, you realize there is a lot of flexibility you can achieve with a bit of configuration. Org-THTML: An HTML template system for org-mode, for show how to use moustache-based templates for generating pages. The matter ended up to be of little or no relevance for my website, because it is made of pages with a simple layout requiring only a bit of CSS.
• Org Mode has limited support for dynamic content (e.g., RSS/atom, sitemap, list of posts). The same effect, however, can be easily be achieved with literate programming in the language of your choice: no need to learn Emacs lisp, if you don’t want to¹.
• Org Mode has no support for bundling assets. This, however, can be implemented by an external toolchain, which is exactly what I do for my website.
• Org Mode does not come with a local server However Emacs and Ruby do and writing the code to preview your website locally requires only a bit of scripting and, more important, ensuring all generated links are relative, so that they work equally well in production and staging.

Drop me an e-mail if you have any opinion or thought on the matter… I will gladly incorporate your comments to improve this page!