Org-mode and Pandoc as a static site generator

What is Org Mode?

Org mode is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

Org is a joyful piece of software. It's a simple yet powerful combination of intuitive markup and ergonomic tooling that (most of the time) just works. The key is that the markup is readable at a glance, and the tools provide some pretty neat ways of interacting with and manipulating it.

It's core components are fairly simple:

headings, lines which start with a number of *'s, provide top-level structure,
inline markup like * * and / / provide styling
blocks (denoted with #+) provide space to do some really cool stuff.
keywords like TODO work with specific tools and provide context

This all comes together perfectly as a tool for literate programming.

Literate blog generation

You may have noticed the source blocks scattered around this site. They define how the content under them is generated. They're just code blocks, but with org-babel I can execute them right in my editor to generate those blocks on the fly! For the site I'm using bash, but babel (as the name implies) let's you write in pretty much anything.

Build the blog list with bash

Is this a little overkill? Yes. But it's way more maintainable than the monster bash script I was using previously.

It's probably not the static site generator for you if you just want to get to blogging, but it's incredibly fun to put together and a great learning experience.

Having the code in the same place as the writing you do encourages you to both maintain it and write more. This could turn into an endless bikeshed, but for me it opens up a ton of possibilities in producing the kind of work I want to.

Getting Started

Org-babel's documentation is somewhat scattered but digging through The Org Manual eventually got me where I needed be. This article on using it for Literate Dev-Ops by Howard Abrams also has a ton of useful information and techniques.

How this site is actually built

The rough idea is to have a bunch of code snippets distributed throughout the site in org-babel blocks. Then we use blocks that look something like this at each level up.

(find-file "./blog/index.org")
(org-babel-execute-buffer )
(save-buffer)

This will go into a specific file and execute all the org-babel blocks contained within. And if that file includes a similar block, it'll go down into others!

And at the top level (the index.org file) we have the code that starts it all.

Getting some HTML

Once all the files are set up, we have a small bash script right at the top to convert all of that markdown to html.

#!/bin/bash

rm -rf _public
root="$(pwd)"

#emacs --batch -l ./build-assets/build.el
for folder in $(find . -type d -not -path '*/\.*'); do
    (cd $folder
     for file in `find . -maxdepth 1 -name "*.org"`; do
         [ -e "$file" ] || continue
         mkdir -p "$root/_public/${folder#./}"

         pandoc -f org -t html "$file" \
                -o "$root/_public/${folder#./}/`basename "$file" .org`.html"\
                --lua-filter $root/scripts/changeLinks.lua \
                --lua-filter $root/scripts/task-list.lua \
                -B $root/static/html/header.html \
                -H $root/static/html/includes.html \
                -c "/static/styles.css" \
                -s
     done)
done

cp -r static _public/

It's pretty small as the heavy lifting is done by pandoc. This time however, this script can stay small as we're letting org-babel take the weight.

What's next?

Well actually writing for one. I've got the infrastructure in place and now it's time to start using it!

Well, there's also some additional infrastructure I'd like to get in of course :)

Get a git-hook in place to run the top level script whenever I commit
Figure out how to handle comments or replies
[0/2] Tie my other org files to the site:
- TODOS,
- Links

EMACS-DOCUMENT