Without boats, dreams dry up

Blogging With GitLab and Hugo

Previously, I attempted to maintain a blog using GitHub Pages. I was very unsuccessful at actually producing blog posts, though. I don’t care a lot about the appearance or maintenance of my blog site. What I want from the experience is the same experience I have writing Rust RFCs (because I have a lot of experience doing that):

  • I write some markdown.
  • I commit and push.
  • Other people can read it.

GitHub Pages gets you pretty close, but it has some limitations, in particular:

  • The only static site generator it supports out of the box is Jekyll. Jekyll is great, but it had several drawbacks for me:
    • It did not support the syntax for syntax highlighting in codeblocks that GitHub flavored markdown has (that is, putting the language name after the opening ticks).
    • It is written in Ruby. I love Ruby, but its an interpreted language, which means I need to manage the environment for any tools I use written in it. I experienced a lot of friction trying to make sure my Ruby environment was right for Jekyll.
  • I wanted my blog to be at $DOMAIN/blog, so that I could leave open the possibility of other content under that domain someday. This required some hacking to make work correctly, and still left some URLs broken.

These aren’t huge issues, but they were annoying enough that as a result I blogged twice in January of this year, and had never gotten around to finishing a blog post since. So last night I started looking for an alternative way to blog. I settled on using GitLab Pages with the Hugo static site generator.

  • GitLab can run any static site generator, and has templates for a wide variety, including Hugo. It also makes it easy to host a site using the URL scheme that I wanted (in fact, its the default).
  • Hugo is written in Go, and has compiled binaries available in the package repositories of every OS I use. It supports syntax highlighted codeblocks.
  • Both seemed to have high quality documentation. GitLab Pages even goes into detail on the background of explaining what a static site is, in case you didn’t know.

Setting it up step by step

  1. I created a GitLab account.
  2. I installed hugo from the package repository for my system. So far, I’ve installed it on Mac OS and Arch Linux, so brew and pacman. Both had it available in their official repositories.
  3. I cloned the https://gitlab.com/pages/hugo repo, which has a set up repository. I made edits to it to satisfy myself, mainly deleting the demo content but also changing a few configurations.
  4. I created a repo on GitLab called blog and changed my remote to track that repo.
  5. I pushed master and waited a few minutes. Without even doing any set up on the website, my blog was being published at boats.gitlab.io/blog!

I’ve since copied over my existing blog posts & written this post as well. For the most part I’ve loved the experience. Neither hugo nor GitLab have given me any grief - I installed hugo, created a GitLab repo, and since then everything has Just Worked.

Only thing I miss

The one aspect of hugo’s interface I haven’t cared for is that the new interface takes a filepath for the file to create. Jekyll just took an abstract “name of the post.” Especially since I prefer to include today’s date in the filename, this means for this post for example I would have to type:

hugo new post/2017-09-28-blogging-with-gitlab-and-hugo.md

I would much rather write:

hugo new blogging-with-gitlab-and-hugo

I haven’t figured out a way to make Hugo support this natively, but I solved my problem by writing a short shell script, which also opens the new post for me in vim:

#!/bin/sh
name=post/$(date -I)-$1.md
hugo new $name
vim content/$name

I still have to edit the front matter a bit, because the date shows up in the title, but I get the impression I could fix that also.