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.” 1 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.2)
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
3. 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
3) This is my
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."