Using org-mode with Jekyll

Introduction

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
#+BEGIN_HTML
---
layout: post
title: "Using org-mode with Jekyll"
permalink: /:title/
tags: hacking
---
#+END_HTML

Configuration

My jekyll blog project looks like this:

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

;; ...

;;;;
;; Projects
;;;;

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

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

Workflow

My current workflow looks something like this:

  1. Add a new file to git/levlaz.org/_org/$DATE-$TITLE.org
  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/levlaz.org/_org/ to /git/levlaz.org/_posts/2016/$DATE-$TITLE.html
  6. Build and Deploy my site with my Rakefile: rake deploy.

Conclusion

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