How to Create a Blog with Hugo and Github

Introduction

Blogging is a common thing right now, you can start blogging using free services with zero configuration like Blogger or Wordpress. On the other hands, did you know that you can build your own blogging platform too — from the ground at no cost.

Introducing Hugo - one of the most popular open-source static site generators written in Go a.k.a Golang. It offers simplicity in building a website while maintaining good performance and flexibility. Unlike other blogging platforms, there is no database, no plugins requiring any permissions, and no underlying platform running on your server, there’s no added security concern.

How about styles? No worry with both the official ones that the Hugo team maintains as well as the community-contributed ones — has a wide range of selection that you can pick based on your need.

Some of the most popular choices include:

You can find a more complete list of both official and community-contributed themes on Hugo's website and Github.

In this tutorial, you will move through step-by-step to build your own blogging platform using Hugo. Starting with installing Hugo, adding themes, adding contents and deploy it with Github pages so everyone can access and read your awesome stories.

Prerequisites

Before following this tutorial make sure you have:

  1. Git - You should have Git installed on your local machine. You can check if Git is installed on your computer and go through the installation process for your operating system by running git --version command. You’ll see git version running on your machine otherwise you have to install git by following this docs.
  2. Github account - This is mandatory in order to host your site later on. Make yourself a Github account signing up on the front page.
  3. Text Editor - You need a text editor such as VSCode, Atom, or Sublime to edit Hugo’s configuration file and add some content to your site. If you are using Mac or Linux and looking for some heat you can use nano or vim text editor that comes out of the box.

Step 1 — Install Hugo

MacOS

Using Homebrew, you can install Hugo with the following one-liner. It may take a while.

$ brew install Hugo

Linux (Debian/Ubuntu variant)

The easiest way to install Hugo on Debian/Ubuntu is by using the provided package via apt-get:

$ sudo apt-get install hugo

Using this method is easy but there is a catch, you might not be the latest version, especially if you are using an older, stable version (e.g., Ubuntu 16.04 LTS). Until backports and PPA are available, you may consider installing the Hugo snap package to get the latest version of Hugo.

You can verify your installation with this command:

$ hugo version

Step 2 — Create a New Blog

Create a new site that will become your blog. The command below will create a new Hugo site in a folder named personal-blog.

$ hugo new site personal-blog

Step 3 — Theme Your Blog

Next thing is to add some themes to your blog. With Hugo, you can either theme your blog yourself or use one of the beautiful, ready-made themes. I choose hello-friend because it is deliciously simple. To install it :

Make sure you are inside your blog directory:

$ cd delicious-blog

Clone hello-friend theme into the themes/hello-friend directory and copy config.toml file from hello-friend to your site.

$ git init
$ git submodule add https://github.com/panr/hugo-theme-hello-friend.git themes/hello-friend
$ cp themes/hello-friend/exampleSite/config.toml ./

Adjust your site configuration by opening config.toml file using your favorite text editor. Fortunately hello-friend gives a clear explanation line-by-line about this configuration.

If you want to add more themes, just repeat the above steps. For most themes, it will work flawlessly.

Step 4 — Add Some Awesome Contents

There are a couple ways you can create content for Hugo. The easiest way is to use Hugo’s cli:

$ hugo new post/how-to-build-a-spaceship.md

That command will create an how-to-build-a-spaceship.md file inside post folder (Hugo will create it automatically if it doesn’t exist) inside the content folder. Edit the newly created content file if you want.

---
title: "How to Build a Spaceship"
date: 2018-04-09T08:51:07+07:00
draft: true
---

## Introduction

A spacecraft is a vehicle or machine designed to fly in outer space. Spacecraft are used for a variety of purposes, including communications, Earth observation, ...

In case you’re curious, the generated file has a certain header, to begin with — it called Front Matter. You can read more details about this Front Matter in Hugo’s official documentation.

Step 5 — Run Your Site Locally

Now, start the Hugo server with drafts enabled to see what’s your site looks like :

$ hugo server -D

Navigate your browser to http://127.0.0.1:1313 and see the magic 🎉. Apply different themes, tweak the configuration file and add more content until you are satisfied with your result.

Step 6 — Deploy to Github

It’s not complete if your site just running on your machine, people still cannot access it yet. From their documentation, you can host your new Hugo website virtually anywhere. One of them is Github Pages, It’s free, easy to set up and supports HTTPS!

Create a YOUR_PROJECT e.g (personal-blog) repository with your Github account. This repository will hold all of Hugo’s content, configuration, and other files.

Create a USERNAME.github.io repository (Yes! You need two repositories). Make sure your USERNAME is your real username, otherwise your site will not showing up properly. This repository will hold a fully rendered version of your site.

Make sure your baseurl key-value in your config.toml reflects the full URL of your GitHub pages repository.

Inside your site directory, create a new git project and add a new remote URL.

$ git remote add origin https://github.com/USERNAME/YOUR_PROJECT.git

Remove public folder and add git submodule. So when you run hugo command to build your site it will live on public folder but have a different remote origin.

$ rm -rfd public/
$ git submodule add https://github.com/USERNAME/USERNAME.github.io.git

Build your site, change directory to public, make a commit and push everything in it. Note, this will publish into https://github.com/USERNAME/USERNAME.github.io repository.

$ hugo -t hello-friend
$ cd public
$ git add .
$ git commit -t 'Initital commit' && git push origin master

Back to root directory, push everything to Github.

$ cd ..
$ git add .
$ git commit -t 'Initital commit' && git push origin master

That’s it!

Your personal page should be up and running at https://USERNAME.github.io within a couple minutes.

Conclusion

In this tutorial we downloaded, configured, and host a complete Hugo site. If you follow all the steps above you should see something like http://husnulhamidiah.github.io (this site). You can take a look it’s source code at my Github.

If you’d like to learn more about how to configure, customize your Hugo site even further and see what else Hugo can do, visit the official Hugo documentation. You’ll find a lot of resources starting from adding a static page, comment, create your own theme and many more.

And, if you have an issue or idea to make Hugo better, feel free to contribute to their Github repository.