How I Write for the Web — Jekyll and GitHub Pages

May 13, 2024

This shows what kind of nerd I am, but the first thing I want to know when I stumble on someone’s website is: what tools/systems do they use? I usually check out the “about” section, but I’ll also look for telltale signs in the source. I have a blurb about this in my about section now, but I thought it might be good to document my tooling and publishing flow in case others were interested. This might all change in the future, but here’s how it all works today.

I use Jekyll as my static site generator. I love static site generators, and will write more about this idea in the future. The short version is: static sites serve a pre-compiled version of what might otherwise be a dynamic site. Instead of doing a bunch of work on the server to fetch templates, data, and resources for every page, you generate all of that on your computer whenever you add new content. Because my content doesn’t change frequently, and the act of compiling takes a couple of milliseconds, what I’m left with is a bunch of static files that are effortless to serve.

I use the Homebrew package manager on macOS to handle most command line software. When setting up a new system, I use it to install a newer version of Ruby than what comes with the OS. I then update my .zshrc to use that version by default. With that installed, I use gem to install the version of Jekyll supported by GitHub Pages. This can be a lot of setup, so I don’t recommend this for everyone. Jekyll has good documentation on the process, so I’d start there.

I use my own custom-developed theme, as well as a few Jekyll plugins. I won’t get into the theming other than to say that free themes are available if you don’t want to build your own. I really like having complete control over the site theme templates in the same way others like tinkering with cars, but I get why most others would want to pick something that looks OK and then start writing.

For plugins, I use jekyll-feed to auto-generate an RSS feed ¹, jekyll-seo-tag to provide images/descriptions for search engines and social platforms, and jekyll-sitemap to produce a sitemap.xml file.

I host all of this using GitHub Pages, which uses Jekyll by default. This integration is the main reason why I’ve stuck with Jekyll even though I find the Ruby ecosystem a bit fiddly. GitHub has some great docs on how to get started, and I can’t say enough great things about this platform. It’s the fastest, most reliable hosting I’ve ever experienced, and it’s free! I’ve weathered a bunch of traffic a few times and the site is always snappy even under load. This is made much easier by the static nature of the site.

So, that’s some of the technical side out of the way. Now a bit about writing. I have a list of potential blog ideas in a section of the Bear editor. My system is far from great, but I recommend having some system to keep track of potential ideas. I also use Bear as the place where writing starts. I write in Markdown, and Bear supports it well. I use the Dracula theme and Hack typeface in Bear.

Once I’m about 90% happy with a post, I’ll start a new post using my custom post command. This makes sure everything is put in the right place and formats the filename and front-matter correctly. From there I’ll paste the content from Bear into the newly created file. I use Panic’s Nova Editor for almost all of my development needs, and it’s also a great Markdown editor. I run jekyll s in the command line to get a local server, and proofread the site in the local version which looks the same as the final version will.

After I’ve done an editing pass, I’ll use the command line version of Git to commit and push the new version of the site up to GitHub. Because GitHub Pages is set to work directly with Jekyll, the final version of the site build happens on their servers. The build process is slower on GitHub’s end, taking 30-45 seconds, but once it’s complete the new version of the site is live.

This process is a lot. It’s built around a bunch of command line tools with hand written Markdown at its core. I definitely don’t recommend this to everyone, but if you’re a developer I think it can be fun to build out your own blogging contraption. A lot of my day is spent on the command line, in an editor like Nova, or writing in Bear, so this flow feels natural to me… but there are some things that I would like to streamline slightly. For instance, I currently manually push posts out to social media sites. Normally this is fine because I don’t post all that often. It’s only become a bit tedious during May, as I’m trying to post something every day.

I do plan to make some more tweaks to my site, and also continue exploring the options around static site generation, but I think I’ll be sticking with Jekyll for a while yet because it’s working. We’ll see how things change once I’m on the other side of Weblog Posting Month.

Update: Robert Birming has collected a list of blogging workflows, which I enjoyed reading over.

It’s actually an Atom feed, but it does the same job. I find most web folks know what I mean when I say “RSS feed”, but some people are confused by “Atom feed”. Both are well supported, so I just used the plugin provided by GitHub Pages, which happens to support Atom. ↩