How to Build a Blog Like This: Intro

Jonatan Ivanov
Dev

The whole thing started with: “I think I want to create a blog”. I had a few ones before, those were either all-in-one hosted solutions or self-installed WordPress sites. WordPress was a tempting pick this time (as always) but I’ve played a little with Jekyll and Hugo recently and I liked them. So I negligently threw the red button with the text “Deploy WordPress” back to the shelf and I brought up a little toolbox that has the text JAM Stack on it from my shed (not bikeshed), also I liked the idea of hosting the blog on GitHub Pages.

What is the JAM Stack?

The JAM Stack stands for JavaScript APIs, and Markup or a slightly longer definition:

Fast and secure sites and apps delivered by pre-rendering files and serving them directly from a CDN, removing the requirement to manage or run web servers.

Or in plain English: generate a static site using markdown (or other markups). Yepp, the whole thing is static (HTML+CSS+JS), no PHP, no server-side JS, you just need something that can host static files. And a Static Site Generator. :)

It has a couple of advantages (maybe these too), I wanted to build this blog using it because:

  • It’s simple
  • It’s fun
  • I can keep the “code” in git
  • I can host it on GitHub Pages

The Static Site Generator

Maybe this is the hardest part, you need to pick a Static Site Generator which is a bigger challenge than it sounds, just follow the link and see. :) Right now the most popular Static Site Generators are:

The first really popular player in this league was Jekyll. GitHub Pages supports it out-of-the-box which means that you don’t need to generate the site and push it, GH will do it for you which makes Jekyll a pretty good go-to choice. Also, its community is big and you will find a lot of help online. On the other hand, it’s is not very fast, and managing Ruby dependencies is something I don’t want to deal with.

I picked Hugo because it is blazing fast, very simple, also seemed fun. :)

Getting Started

Hugo has great documentation, just check it’s Quick Start guide and nothing will save you from having a static site in a few minutes from ground zero. Adding themes as git submodules is a pretty convenient way to download and update them later.

Right after I generated the site, I created an .editorconfig file because (EditorConfig is awesome) I like to keep things tidy even if they are just a few config files and some markdown. Also, I immediately added a Makefile so that I can automate a few things and have a simple “build system” (check out GNU Make).

EditorConfig

Other than setting the basics, there are two important parts in my .editorconfig file:

Makefile is indented with tab:

[Makefile]
indent_style = tab

while two spaces at the end of the line means a line break in Markdown:

[*.md]
trim_trailing_whitespace = false

Makefile

I wrote a few targets so that I can:

  • Start the dev server: make server
  • Produce the static files: make build
  • Clean the build output: make clean
  • Clean and build: make all or just make
  • Update the theme: make update
  • Deploy the site: make deploy

After these, nothing prevents you to work on your site efficiently, in the next post I’m going to explain how to proceed.

Posts in this series