Blogging with Org-Mode and GNU Make
12 January 2021
Update Oct 2021
I wanted a simple webspace where I could write a combination blog/personal notebook to collect articles about things I wanted to refer back to and just stuff that I found interesting. I tried a lot of prefab CMSes and static site generators:
- The one built in to
The inevitable outcome
Just as any sufficiently-complex C or Fortran program contains a slow, bug-ridden, informally-specified implementation of half of Common Lisp, I suppose that the inevitable conclusion of the search for a static site generator means you end up just writing your own.
In my case, my criteria were simple.
- Small page size, ideally 100 kB or less including images, except for articles with many pics perhaps
- No docker or similar bullshit
- Ideally composable within org-mode
It turns out that nothing really meets these criteria except possibly
org export, which is built in to org-mode and is very
complicated. The default export has individually-numbered IDs for each
div and all kinds of boilerplate. I'm a smart guy but I spent two days
trying to figure out how to customize it to my liking and I gave up
because it was too much work. The documentation is woefully lacking, to
put it mildly.
I have a
content/ folder in the project root where the
Makefile lives. Within the content folder are all the articles I write,
could make it and depends mostly on the cat(1) and
Concatenating for fun and profit
I felt like my ideal case was having org mode shit out just an html snippet, i.e. not an entire web page, and then concatenating that with a header and footer that I would write myself. I gave it the good old college try, but for the life of me I could not get this to work using org mode, so I turned to pandoc instead. My process is simple:
Write the article in org-mode, which allows explicit inclusion of html tags and elements where required. I also write a
.metafile which is just a few lines from the HTML header.
Invoke Pandoc to translate org to html:
$ pandoc input.org -o output.html
Hand-craft a header and footer, then catenate it all together
$ cat header.html article.meta output.html footer.html
Rsync everything to a server.
$ rsync -a --delete staging/ [email protected]:/home/bla/path/to/www/
And that's it! I do this whole site via this method, easily done via
make-deploy. The source code is available on github.