Starting blogging with Hugo and Github pages

Jun 3, 2017 · 2 minute read

Why Hugo ?

My requirements when starting this blog where:

support Markdown
a preview mode and support for drafts
good syntax highlighting
good theming support

There are a lot of options out-there that check some (if not all) of the above boxes:

generate a site and host it somewhere, ideally free (ton of options from here)
host the blog platform yourself (usually wordpress deployed on a hosting provider)
use a hosted platform (wordpress.com, ghost, medium, postach.io, etc)

For me the first options was the best and, after less than 10 minutes of google searches and 2 minutes of experimenting according to the quickstart instructions, I’ve settled on the Hugo + Github pages combination

Hugo checks all the requirements above and some more, all while being a single binary that is very fast

Summarizing the linked quick start instructions, starting writing with Hugo is as simple as:

brew install hugo
mkdir blog && cd blog

# create the site
hugo new site .

# create a post
hugo new post/welcome.md

# auto-generate and serve the blog while you are editing the post
hugo server -w --buildDrafts

# browse your blog
open http://localhost:1313/

It’s that simple! Of course there are other things you can do:

installing a good theme from a huge variety on themes.gohugo.io
change site-wide configurations like syntax highlight theme

At the end of these your blog should contain these files:

❯ tree -L 1
.
├── archetypes
├── config.toml
├── content     <- this is were your post/welcome.md file is generated
├── data
├── layouts
├── public      <- this is your site generated by hugo (this will be pushed to GitHub pages in the yout-username.github.io repository)
├── static
└── themes      <- this is were you clone your themes

Pushing your blog to GitHub pages

First step is to go on github.com and create an empty repository called your-username.github.io. Note that the name of the repo must have this exact format.

Next, edit your config.toml file and change baseURL = "http://your-username.github.io/"

Now, follow these steps to push your hugo-generated site to this repo and have your blog available on http://your-username.github.io/ (with a delay of 10 minutes or so)

Next, go to http://your-username.github.io/ to see your blog.

DONE! You’re blog is live