Using org-mode with Jekyll


Since my journey into Google Docs’s Hell I have been getting more reacquainted with org-mode for other purposes as well. Traditionally, I have been writing this blog using Markdown and publishing it with Jekyll. I love Markdown, and while it is fine for most cases, but what better way to gain more experience with org-mode than to blog with it! The best tutorial that I have found so far is this one from the org mode web site: Using org to Blog with Jekyll. One “gotcha” that I have ran into so far, is everything breaking if I include a table of contents (which happens by default when you export to HTML). The simplest solution for this is to add the following to the top of your org flavored file.

#+OPTIONS: toc:nil

This allows the front-matter to be exported properly. I am also choosing not to include section numbering for my posts. So the complete front-matter for this post looks like this:

#+OPTIONS: toc:nil num:nil
layout: post
title: "Using org-mode with Jekyll"
permalink: /:title/
tags: hacking


My jekyll blog project looks like this:

;; File ~/.emacs.d/customizations/setup-org.el

;; ...

;; Projects

;; Blog
(setq org-publish-project-alist
         ;; Path to org files.
         :base-directory "~/git/"
         :base-extension "org"

         ;; Path to Jekyll Posts
         :publishing-directory "~/git/"
         :recursive t
         :publishing-function org-html-publish-to-html
         :headline-levels 4
         :html-extension "html"
         :body-only t


My current workflow looks something like this:

  1. Add a new file to git/$DATE-$
  2. Add the front matter shown above
  3. Blog my heart out
  4. Check my spelling with ispell
  5. Publish the org file with C-c C-e P p , this moves the file from git/ to /git/$DATE-$TITLE.html
  6. Build and Deploy my site with my Rakefilerake deploy.


There is definitely some room for improvement here such as macros for dumping in the front-matter, easier deployment, and more automation. I plan on seeing what I can do to make this process a bit smoother for me and update this post when I do.

Leave a Reply