Latest Post

Using org-mode to blog with Jekyll

Some years ago I moved to Jekyll from Wordpress and have been hosting this blog as a statically generated website on S3. Having recently discovered Emacs' org mode I wanted to see if I could write blog posts with it. Considering that this is the emacs community it was probably silly to doubt that nobody had done this before. It turns out that there's a whole post specifically about this on the org mode site: Using org to Blog with Jekyll. It's a little out-of-date as in org 8.2 the HTML export publishing function has changed, but that's the only difference.

The process of using org-mode to blog with Jekyll involves using the org mode HTML export to publish a body-only export of your org-files. This means that it exports only the HTML inside the <body></body> tags and doesn't include anything else. It then places these output files inside Jekyll's _posts directory which Jekyll interprets and serves up. The trick is that you need to include your YAML front matter as an HTML block at the top of the org-mode post so that when org exports it it leaves it as it is:

layout: post
title: Using org-mode to write Jekyll blogs

My blog post goes here.

This BEGIN_HTML block doesn't get HTML processed and leaves a file in the correct format for Jekyll to read.

Inside your emacs configuration we then set up an Publishing Project which adds a new Publish menu option to the menu you'd see with C-c C-e normally. You can use C-c C-e P x to publish any publishing project from within any org-mode buffer, or you can run the function org-publish <select project> or org-publish-all from any buffer.

I would suggest reading the documentation page linked above and adapting to the folder structure it recommends. You'll end up with something like this:

├── jekyll
│   ├── archives
│   ├── css
│   ├── _drafts
│   ├── images
│   ├── _includes
│   ├── _layouts
│   ├── _posts
│   ├── _sass
│   ├── _site
└── org
    ├── images
    └── _posts

Inside org/_posts I'll have files as normal but with .org extensions such as

Inside my emacs configuration I have the following:

(setq org-publish-project-alist
     ("org-mfoot" ; Export my blog to the Jekyll format for ~jekyll build~
       ;; Path to your org files.
       :base-directory "~/repositories/"
       :base-extension "org"

       ;; Path to your Jekyll project.
       :publishing-directory "~/repositories/"
       :recursive t
       :publishing-function org-html-publish-to-html
       :html-extension "html"
       :body-only t ;; Only export section between <body> </body>

       :section-numbers nil
       :with-toc nil
       :auto-index nil
       :auto-preamble nil
       :body-only t
       :auto-postamble nil

      :base-directory "~/repositories/"
      :base-extension "css\\|js\\|png\\|jpg\\|gif"
      :publishing-directory "~/repositories/"
      :recursive t
      :publishing-function org-publish-attachment

    ("" :components (

If we see the last bit first, we've defined a project called This is the name of the publishing project. It's a wrapper for two smaller components - org-mfoot and org-static-mfoot. org-static-mfoot uses the org-publish-attachment function which simply copes files without any processing directly from the source to the destination folder. The base-extension limits it to the typical file types I'd host, so putting anything inside the folder matching those extensions would have org-mode copy them to the publishing-directory folder with a matching directory structure, creating those directories if it needs to. The org-mfoot project uses the org-html-publish-to-html function which processes all of the org files. It disables a bunch of things and importantly sets :body-only t. This is the magic that lets it work with Jekyll.

I had a problem with images that the documentation didn't cover. When using links in the format [[../images/2015/11/foo.png]], org-mode would only generate relative paths from the output folder structure. As I'm storing the images in a parallel directory structure, this didn't work. While these worked in the blog's index page, the images would 404 when viewing the individual blog page because the URL changed. I found the solution in an excellent StackOverflow answer and this worked perfectly. I added the following to my config file:

(defun org-custom-link-img-follow (path)
   (format "../images/%s" path)))

(defun org-custom-link-img-export (path desc format)
   ((eq format 'html)
    (format "<img src=\"/images/%s\" alt=\"%s\"/>" path desc))))

(org-add-link-type "img" 'org-custom-link-img-follow 'org-custom-link-img-export)

and then changed images to use the img: prefix:


Now I can write blog posts inside org-mode in emacs, run org-publish-all, check the generated site with my background process running jekyll serve, then push the site to S3 with s3_website. Nice.

Recent Posts

Switching from Vim to Emacs

Last month I switched to Emacs after after 7 years of using Vim. I tried Emacs for the first time on a colleague's recommendation and after a month of using it I won't be going back.

Vim isn't removed from my workflow. For quick changes of single files and for modifying files if I'm already on a server, vim will be my go-to editor. For everything else, emacs has taken over.

It took a while to get emacs configured in a way that I liked, able to provide all of my favourite features of vim and then many more features on top of that. I did a fair amount of customisation (I believe all emacs users do this) as the out of the box user experience is truly abysmal. The defaults for simple things such as scrolling the page were crazy. The key combinations made no sense at all. I had to use my text editor to debug my text editor. Then I gave in and tried out evil-mode, which provides vim-style keybindings for emacs. If you're used to vim this is fantastic. I don't need to learn a whole new set of commands for editing. Pretty much everything I used in vim works the same way on emacs. I have almost the whole set of vim features I used and then a whole host of things I could never do before. I said that I haven't removed vim from my workflow completely. I still prefer using vim for quick edits and for working on remote machines (but, ofcourse emacs can edit remote files, even SSHing through multiple boxes to get there). By using evil-mode I don't lose the vim skills that I'd be using editing those files.

For most of my configuration I trawled the internet for peoples' .emacs files, tested each setting and imported the ones I liked. For the rest I searched for answers online or in the in-built help system when I found something I didn't like. Sometimes this means using other modes (essentially libraries providing functionality), sometimes it means using different functions instead of the built in ones. Suddenly you realise that everything is configurable.

Don't like typing 'yes' or 'no' at confirmation prompts? Change the function that gets called when emacs needs to ask for a yes or no response.

(defalias 'yes-or-no-p 'y-or-n-p)

Want to see more information about files in a directory such as human-readable sizes? Configure the ls switches used to show information about files on the filesystem:

(setq dired-listing-switches "-alh")

Want to automatically enable the spell checker for certain file types? Want it to check spelling as you type, continuously? Want to be able to save words to a personal dictionary?

(add-hook 'org-mode-hook (lambda () (flyspell-mode)))

Want that spell checker to only run on comments and strings when you're editing code? Use the programming version of the spell checker:

(add-hook 'c++-mode-hook (lambda () (flyspell-prog-mode)))

Want emacs to run the a Ruby syntax checker and linter as you type? Install rubocop and run flycheck:


It's all there and it's all configurable. Once you experience configuration this way you see how much more powerful it is using a programming language to perform configuration rather than listing key-value pairs. I consider myself pragmatic rather than religious about text editors. I wouldn't be using a tool if I didn't think it was the best one for the job. I spent a long time hearing emacs fans raving about what it could do but I needed to spend the time actually trying it out for myself before I understood why they were so zealous.

And then I discovered Org mode. Org mode is astonishing. I can track every issue I'm working on, support tickets I have in play, thoughts about features that haven't made it to JIRA yet, store source code (highlighted in the correct language's syntax highlighter), execute bash scripts from inside the text file, run MySQL queries and see the results formatted in a table, even edit spreadsheets with actual cell and column formulae. I got emacs to export org-mode files that Jekyll can use so I can write blog posts in org-mode. I used org-babel-load to store my emacs configuration in a well-documented org-mode file, which emacs then publishes alongside my blog posts in an HTML file This means that my configuration and the documentation for my configuration are the same file. There's a huge amount of features in org-mode and it's definitely worth a separate post. My goal here is just to introduce some of the things that make my life easier every single day.

It's only now that I begin to really understand the jokes about people who use emacs as their operating system. Once you can do everything in one place, why would you leave it?


Accidental double exposures

Multiple exposure images are a lot of fun to make and it's always exciting to see the final output. On film cameras they can be deliberate or accidental. They could be caused by careful planning, lack of thought before acting, or mechanical failure. In the case of these two produced with my Nikon FM2N I had no intention of taking photos like this at all, yet they're some of my most memorable photos from trips last year

The first photo is in Athens near Monastiraki, not far from the Acropolis. Two separate night time shots of city streets combined to make something that doesn't quite represent either:


The second shot is from the Fushimi Inara Shrine near Kyoto, Japan. The shrine itself is stunningly beautiful and I was lucky enough to visit on a lovely sunny day when the cherry blossoms were blooming. I think this was caused by me accidentally tripping the multiple exposure latch on the Nikon.


I love getting shots like this back from the lab. It's usually very difficult to tell from the negative what is going on so you must wait for the scan to see the full awesomeness of such happy accidents. Some cameras (including my FM2N) actually support multiple exposure by re-arming the shutter without advancing the film. There also are some very creative people out there making full use of this - deliberately composing and shooting scenes for a desired effect. I highly recommend having a search around on Google Images and Flickr for some more examples, and I suggest you start here.

To see more posts, visit the archives.

subscribe via RSS