Blogging with Lisp

Written on 2018-11-21

So, I finally have my blog up and running. After several years of thinking: “I really ought to write an article on that thought.” ¹ And two afternoons of trouble-shooting Linux, Lisp, and LAMP problems.

Because of course, if I was going to write a blog I would host it myself. And Wordpress is overkill for what I am planning, all I need is a simple static site generator working from markdown. How hard can it be?

Well, it started with the choice of generators. I'd read about two or three good options before - trouble was, I couldn't remember their names. And DuckDuckGo came up with a list of 458 of them. Eventually I settled on coleslaw, mainly because it is written in Common Lisp and looks fairly well maintained. I've been doing a lot with Lisp again lately and have been trying to get deeper into the Common Lisp ecosystem - so this seemed like a good place to go.

So I headed over to my server, brought up a REPL and installed the Quicklisp package. So far so good. But then the real difficulties started. I also host a Gitbucket instance (see the project homepage) for my private source code. According to the coleslaw website, I should have been able to stick a small shell script into my server repo as a git hook, so my blog is automatically updated whenever I do a git push. It didn't work. After trying all sorts of fixes, I eventually discovered an obscure thread that told me that Gitbucket doesn't support git hooks at all. Well, that sucks. Especially since the first afternoon (and part of the evening) was now gone.

Well, if I can't automate deployment on the server, perhaps I could automate it locally. With this intent I started on the second afternoons work. And after various pitfalls, I finally got it working. (Pro tip: Keeping your work files on an NTFS partition is great if you occasionally need to access them from Windows. But its lack of user permissions plays merry hell when you have to interface with ext4, or programs that expect to be running on ext4.²) Anyway, I now have a setup where I have all my blog pages and posts stored as markdown documents in a git repo (created locally and hosted on my server), alongside the theming templates used by coleslaw. Plus I have a local post-commit hook that will publish my changes as soon as I commit them ³. So in the end, that's pretty good going. Just took a long, winding road to get here…

Summary coleslaw is, on the whole, a really neat little program. If you're used to working with Common Lisp and Quicklisp, I can recommend it. The documentation is a bit on the minimalist side though, and there aren't a lot of tutorials available. So prepare for a bit of trial and error, and don't forget to Read The Source. But it serves my purposes well and I'm quite pleased with the result.

- - -

1) I miss the days of CATO…

2) coleslaw uses rsync -a to move files around. This attempts to preserve file permissions - which obviously causes problems with NTFS. To work around this, your theme templates, your static directory, and your staging directory need to be on ext4. I do this by copying the first two to the staging directory via a shell script (see below). The Github ticket requesting a fix is here.

3) This is my .git/hooks/post-commit file:

echo "Copying theme..."
cp -a ~/TerraNostra/my-readable-theme/* \
    ~/.coleslaw/themes/my-readable
chmod -R 755 ~/.coleslaw/themes/my-readable

echo "Copying static content..."
cp -a ~/TerraNostra/static-content/* ~/.coleslaw/static/
chmod -R 755 ~/.coleslaw/static

echo "Building HTML..."
sbcl --noinform \
    --eval "(ql:quickload :coleslaw)" \
    --eval "(coleslaw:main \".\")" \
    --eval "(quit)"

echo "Done."

Tagged as computers, lisp, terranostra

• Next →