How to Redesign a Blog

For several years, I ran (and, more often, neglected) a blog over on Google Blogger. I have no particular complaints about their service, but it simply wasn’t a great fit for me, so I switched over to a new setup. A couple of the software development blogs that I follow have gone into some detail on how they redesigned their own sites (examples are Troy Hunt and Dan Luu), and it’s made for some interesting reading, so here are my own notes on the process I used.

Choose a platform

Broadly speaking, there are a few types of platforms:

1. A third-party service, like Blogger, Tumblr, or Svbtle.
2. Medium. Although technically just another third-party service, Medium is widely praised for its high-quality tools for writing and commenting and for the help that the platform gives in promoting its writers’ content.
3. Blogging or CMS software like WordPress or Ghost. Choosing one of these brings a second choice: You can host it yourself (for more control and more time investment), or use for a service such as WordPress.com (for more simplicity and either ads or more financial investment).
4. Static site generators, like Jekyll or Gatsby.

Any of these options can make for a good blog, and all of them have their own advantages. For me, I liked the idea of controlling my own site (a strike against third-party services) and of not having to spend a lot of time maintaining a server (a strike against hosting my own blogging or CMS software) or spending more money on hosting. A static site generator also appeals to me as a geek: going full circle back to the early days of the World Wide Web as a collection of HTML documents, only now automatically and elegantly generated using modern software toolchains. Additionally, I like the idea of blogging like a hacker: maintaining a blog using tools and a workflow similar to what I use for the rest of my career.

Jekyll is by far the most popular of the static site generators, so I went with that. Life is not a popularity contest, but popularity in software is worth a lot: the more popular a piece of software is, the more it benefits from network effects, giving it more development effort, more of a supporting ecosystem of utilities and add-ons and howtos, and a greater likelihood that someone else has found and fixed your problems before you run into them.

So Jekyll it is.

Think about your design

Will you want the blog title at the left or the top?

Do you want a hero image? (Create Commons-licensed photography makes this less intimidating than it otherwise would be.)

What domain name will you use? Some variation of your name seems common.

Do you want the home page to contain full articles, article excerpts, or simply an index of posts?

What gadgets do you want—a Twitter feed, tags, a date tree, social media links, something else?

You don’t have to have final answers now, and all of this can and will be changed later, but spend a bit of time paying attention to other blogs and identifying elements that you like; it will guide your decisions later as you set up Jekyll and pick a theme.

Get started

Jekyll uses Ruby, so install rbenv to manage your Ruby environments. (RVM works too.)

Follow Jekyll’s docs to get started.

Migrate any existing blog content. Jekyll makes this really easy; this is an example of the benefits of popularity and network effects.

Pick a theme

Browse Jekyll Themes and pick one that you like, or check the much shorter list of officially supported GitHub Pages themes, or check out various premium themes like JekyllThemes.io’s. Popular choices include Minimal Mistakes, HPSTR and Neo-HPSTR, Hyde and Lanyon, and any of the GitHub Pages themes. Googling for “jekyll themes” will find many more recommendations.

Test it out

Current versions of Jekyll, and newer themes, allow you to install the theme as a Ruby gem, so that it’s easily to install, easy to upgrade, and cleanly separated from your blog. The only alternative, and one that’s still recommended by older themes, is to download a copy of the theme (or fork it on GitHub) and start editing your personalizations and content into it directly.

Every programmer knows, of course, that the library approach (keeping third-party code cleanly separated) is better.

In this case… every programmer may not be quite right. The fork-and-edit approach is simply simpler: some themes might not have a gem version, or the gem version may place restrictions on what Jekyll gems it will work with. Some of the more advanced themes have particular requirements for Jekyll configuration and site layout (the fork-and-edit approach would give you this for free, while the gem approach would require additional tweaking). GitHub Pages in particular restricts which gems you can use, while fork-and-edit should allow most any design.

More fundamentally, a theme isn’t exactly like a third-party library that you use through well-defined interfaces and regularly upgrade to benefit from bugfixes and new features; many themes are almost more of a scaffolding for your own site, which you then tweak and customize and make your own. And fork-and-edit makes this easy: it’s very, very obvious where your layouts and CSS and templates are coming from and how to customize them. If the theme you pick already does everything you want (so tweaking may not be needed) and is still actively developed (so clean upgrades are useful), there’s nothing wrong with gems, but don’t hesitate to take the fork-and-edit approach if it makes more sense.

Set up hosting

For software geeks, the standard provider for free Jekyll hosting is GitHub Pages. Simply create a repo called yourname.github.io and push your Jekyll site to it, and GitHub will automatically build it.

The biggest disadvantage of GitHub Pages is that their Jekyll setup is somewhat restrictive. In order to simplify their maintenance and manage server load, there’s a fixed list of supported versions and plugins, and features such as Jekyll’s Latent Semantic Indexing (which it uses to create the “Related Posts” section that you see at the bottom of many blog) are unsupported. You can work around this by setting up a separate repo for your Jekyll site and only publish the generated site to the yourname.github.io repo, but that’s more of a hassle.

Fortunately, there’s an alternative: GitHub’s competitor GitLab offers free, built-in CI, and thanks to this, GitLab Pages supports any configuration of any version of static site generator that you can get to work. It’s a little slow (a few minutes to build even a small blog), and error messages can be a bit cryptic, but they have good documentation and plenty of example projects to use as starting points. (One tip: The build directory of the CI version of your blog has to be called public.)

I’m not sure how the folks at GitLab decided to come up with this feature. (“Competing with the 800 lb. gorilla of the open source hosting business is really hard. What can we do to come out ahead?” “I know! Instead of just offering free repositories and issue tracking and wikis and web sites, we’ll offer free continuous integration and builds and allow features that GitHub themselves have ruled out as being too resource-intensive!”) Seems crazy, but it’s awesome.

Get a domain name

There’s absolutely nothing wrong with the free yourname.github.io or yourname.gitlab.io domain provided by GitHub Pages and GitLab Pages. If you want your own domain, though, you can pick one up for maybe $12 a year (depending on specifics). There are lots of registrars nowadays: Google Domains, GoDaddy, Namecheap, and countless others.

Namecheap came recommended to me, and I’ve been impressed with them so far. They have competitive pricing and very helpful docs and service, and they’re not interested in pushing a bunch of obnoxious ads or dubious additional products (unlike some hosting providers and SSL CAs that I’ve dealt with).

Whoever you go with, make sure you get WHOIS privacy. Not exposing your personal address and phone number to the world is worth it, even if it costs a few extra dollars a year.

Set up SSL

The web is moving toward using HTTPS everywhere. This is a good thing. Fortunately, it’s now very easy to set up SSL, even for a free personal blog. There are three main approaches:

• Your host may provide it by default. GitHub Pages and GitLab Pages do, as long as you stick with their default yourname.github.io or yourname.gitlab.io domain.
• Cloudflare offers Universal SSL, which involves them providing a free proxy to your site and adding free SSL using their own certificates.
• Let’s Encrypt provides free SSL certificates to everyone.

Let’s Encrypt is a great service, but setting it up for a static third-party-hosted site is a little fiddly. (Check out these GitLab Pages instructions to see what I mean.) Setting up Cloudflare is pretty painless, so I recommend that.

Create a favicon

A favicon is optional, but personally, I like having one, just to make open browser tabs visually distinctive. Fortunately, you can create a favicon pretty easily, even without any artistic skills:

1. Instead of trying to draw something yourself, pick something you like from any of the numerous free typography, emoji, or icon sets available online.
2. Set up a web page, IDE, or other piece of software with whatever letter(s), glyphs, or icons you select. Set the font size big, or zoom in a lot in your browser, so you can get a nice high-quality image.
3. Take a screenshot using the program of your choice. (For Windows, I recommend Greenshot.)
4. Trim and clean up the image if needed, and resize it to at least 70x70.
5. Upload it to RealFaviconGenerator.

Octopress

If you’re running Jekyll, you’ll hear Octopress mentioned. Somewhat confusingly, there are actually two Octopresses:

• Octopress 2 is “basically some guy’s Jekyll blog you can fork and modify”. As I understand it, it’s a prepackaged Jekyll distribution, providing a Jekyll configuration with bundled themes and plugins and command-line tools. It’s pretty popular, but it’s mostly unmaintained at this point.
• Octopress 3 is just the command-line tools from Octopress 2, redesigned to be easy to integrate into your own blog.

Octopress 3 isn’t necessary, but it has some useful functionality once you get more into blogging.

Set up comments

The biggest disadvantage of a static site is, of course, that dynamic content like comments becomes much harder to integrate. Different sites take different approaches to dealing with this:

• Don’t have comments.
• Use a third-party service. Disqus is probably the best known. They do not have the greatest reputation.
• Use Discourse. If it’s good enough for Jeff Atwood, it should be good enough for anyone. ☺
• Use a service like Staticman or Jekyll AWS Comments to take comments and turn them into commits to your static site that are then immediately published. This takes the “static site generator” concept to its logical conclusion and lets you keep all of your site in the same static, version-controlled repository, although I’m concerned it may be a bit of a square peg, round hole solution.
• Direct people to Twitter.

I don’t yet have a good solution here, but if you have any feedback, let me know in the comments sec—err, on Twitter.

Updates: Further ideas

Instead of using a unique font or glyph for your favicon, hand-write your initials, for a personal touch.