sanjay-saxena.github.io

by Sanjay Saxena

              

powered by Hugo
© 2017 Sanjay Saxena. All rights reserved.

First Blog with Hugo

Apr 6, 2017

When I was asked to create a blog site, I started researching the popular blogging platforms. However, I was getting overwhelmed while trying to understand the pros/cons of paid vs free platforms and the strategies of hosted vs self-hosted and the issues with each of them. That is when I came across Hugo in a comment section of one of the blogs that I was reading. And, according to the comment, the only thing that was needed to create a site using Hugo is a Github account.

Since I already have a Github account, the comment appealed to the developer in me and I decided to investigate Hugo. As part of my investigation, when I learnt that Hugo is not only open source and completely free but the generated site is also fast(because of static assets) and served directly off of Github using https://<username>.github.io URL, I was sold! But, when I learnt that Hugo allows content to be created using Markdown, I was blown away!

Having decided to create a static HTML site running on Github using Hugo, I wasn’t sure how successful my efforts would be as I didn’t know Golang and the thought of handcrafting HTML pages and CSS style classes wasn’t too appealing. Then, I stumbled upon Nate Finch’s excellent posts at nfp.io to make me a true believer in Hugo. Using the layouts and the theme templates from Nate’s Github repo as the starting point, I was able to personalize them to create the code for my static HTML site. Though I have a long ways to go to automate things using Wercker for CI and other hooks, I think I am in much better shape as I got the basic stuff working.

This blog includes steps that one can take to create a static HTML site running on Github using Hugo. To be able to create a static HTML site on Github, you must sign-up/register with Github and get a username. In the remainder of this post, treat <username> as a placeholder for your Github username.

Install Hugo

Based on your operating system, you can follow these instructions to install Hugo on your machine.

Create Github Repositories

Sign into Github and create the following two public repositories and select the checkbox to initialize the repository with a README:

Register Site with Disgus

Hugo has inbuilt support for Disgus to manage comments on any of the content that is served from your generated static site. While registering your site with Disgus, you can specify the site name as either <username>.github.io or your own vanity domain name to create a Disgus shortname. Then, all you need to do is specify the shortname in Hugo’s config.toml using disgusShortname parameter.

Setup Working Environment

Once the repositories are created, here are the steps for creating a working environment that would allow you to create content:

Create Hugo Site

$ cd ~; mkdir Workdir; cd Workdir
$ hugo new site <username>-hugo

Sync with the Git repo

$ cd ~/Workdir/<username>-hugo
$ git init
$ git remote add origin https://github.com/<username>/<username>-hugo
$ git branch --set-upstream-to=origin/master master
$ git pull origin master

To generate the static HTML content, you will have to execute hugo command from <username>-hugo folder. By default, hugo generates the static artifacts in a sub-folder named public. These artifacts will have to merged/pushed to the https://github.com/<username>/<username>.github.io repository. To make this a bit easier, we can create a symbolic link as shown below:

$ cd ~/Workdir
$ git clone https://github.com/<username>/<username>.github.io.git
$ cd <username>-hugo
$ ln -s ../<username>.github.io public
$ echo public > .gitignore

Copy Nate’s Templates

To get started, you can copy Nate’s templates as shown below:

$ cd /tmp
$ git clone https://github.com/natefinch/npf
$ cp -r /tmp/nfp/archetypes ~/Workdir/<username>-hugo/
$ cp -r /tmp/nfp/layouts ~/Workdir/<username>-hugo/
$ cp -r /tmp/nfp/themes ~/Workdir/<username>-hugo/
$ cp -r /tmp/nfp/static ~/Workdir/<username>-hugo/

Update config.toml

You can update the minimal ~/Workdir/<username>-hugo/config.toml that Hugo generated. For inspiration, you can look at Nate’s /tmp/npf/config.toml. You should certainly update the following site attributes and parameters in:

Update Other Files

Here are some of the other files that you need to update:

Merge Changes

Once the scaffolding is created, you can push it to https://github.com/<username>/<username>-hugo repository as shown below:

$ cd ~/Workdir/<username>-hugo
$ git add .
$ git commit -m "Initial commit"
$ git push -u origin master

At this point, your environment is ready and you can create content.

Add Hello World Blog

Now that you environment is all set, you can add the first blog entry using the following command:

$ cd ~/Workdir/<username>-hugo
$ hugo new blog/hello-world.md
$ cd content/blog

Edit hello-world.md by changing draft = true to draft = false. Also, update the title by making it more user friendly and use markdown syntax to add a title and text as shown below:

+++
type = "post"
date = "2017-04-07T19:32:12-07:00"
title = "Hello World using Hugo"
draft = false
+++

Hello World using Hugo
======================

My first flog with Hugo!

Preview Content

Using Hugo’s inbuilt server, you can preview the content using the following command:

$ cd ~/Workdir/<username>-hugo
$ hugo server --buildDrafts

Then, you can point your browser to http://localhost:1313 to preview the content. You can click on the Posts link in the side-nav to look at the list view of your posts.

Generate Content

Once satisfied, the content can be generated using the following commands:

$ cd ~/Workdir/<username>-hugo
$ hugo

This will result in the static HTML artifacts to be generated in the public sub-folder that is a symbolic-link to ../<username>.github.io folder.

Merge Changes

Note that the hello-world.md will be merged/pushed to https://github.com/<username>/<username>-hugo repository and the generated content in the public sub-folder will be merged/pushed to https://github.com/<username>/<username>.github.io repository.

Here are the steps to merge hello-world.md to https://github.com/<username>/<username>-hugo repository:

$ cd ~/Workdir/<username>-hugo
$ git add .
$ git commit -m "Added hello-world.md"
$ git push -u origin master

Here are the steps to merge generated artifacts to https://github.com/<username>/<username>.github.io repository:

$ cd ~/Workdir/<username>-hugo/public
$ git add .
$ git commit -am "First checkin with Hello World blog"
$ git push -u origin master

Load https://<username>.github.io in your browser and checkout your shiny little site! If you want to use a vanity domain name instead of https://<username>.github.io, then you need to register with a DNS provider and follow these instructions to add your custom domain to your Github site.

From this point on, whenever you need to add a new post, it’s just lather, rinse, and repeat the aforementioned steps outlined for adding the Hello World blog!

w