Hello World

The first blog, and how to 'Hugo' a blog - How to use Hugo to build a personal blog, and publish it onto GitHub Pages.

May 15, 2022 2 min read

Hello World!

This is my first blog post. Today, let’s talk about writing a Markdown blog with Hugo, and eventually deploying it on GitHub Pages.

Hugo is a static HTML and CSS website generator, which allows us to concentrate on the contents rather than the layout tricks.

Environment:

Windows 10 (64-bit)
Ubuntu 20.04 LTS, Windows Subsystem Linux 2

In this section, we will prepare the tools.

NOTE: Please check out the official websites for detailed guidance. I may not cover full details.

In this section, we will use two powerful tools: git and golang

$ sudo apt-get install git golang

$ git config --global user.name "Your GitHub Username"
$ git config --global user.email "Your GitHub Email"

Install from GitHub Release package, choose the latest package with the name ‘extended’, e.g., “hugo_extended_0.98.0_Linux-64bit.deb”

To install it, type:

$ sudo dpkg -i ./hugo_extended_0.98.0_Linux-64bit.deb

NOTE: DO NOT use apt to install hugo, because its version of hugo installation package has already been outdated and can thus cause runtime errors.

$ ssh-keygen -t rsa -C "Your GitHub Email"

And then add the public key in ~/.ssh/id_rsa.pub to the GitHub Dashboard, and test connection:

$ ssh -T git@github.com

In this section, we will initialize the blog.

$ hugo new site "NewSite"
$ cd NewSite

This will prepare the submodule environment for Hugo themes.

$ git init

In this section, we will pick up a beautiful theme for the new site.

Unlike Hexo, an alternative blog generating tool, the Hugo does not consist of a default theme, so let’s pick theme(s) for Hugo.

And I prefer the hugo-Clarity, so I type these commands:

# 1. Getting started with Clarity theme
$ git submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity

# 2. copy the essential files to start
$ cp -a themes/hugo-clarity/exampleSite/* . && rm -f config.toml

NOTE: We use git submodule here, rather than git clone. Because we already have a .git configuration.

$ hugo server --buildDrafts=true

Well done, now we can preview our blog (including drafts) with the URL shown in the Terminal.

In this case, my URL to preview is http://localhost:1313/

In this section, we will talk about how to upload a new post and do some tweaks.

$ hugo new post/post-1.md

NOTE: the folder is ‘post’, not ‘posts’

Open the newly generated file in ./content/post/post-1.md, and change its header

---
title: "Hello World"

description: "The first blog, and how to 'Hugo' a blog"
summary: "How to use Hugo to build a personal blog, and publish it onto GitHub Pages."
tags: ["Misc"]

date:    2022-05-15T19:28:07+08:00

math: false
mermaid: false
utterances: true

draft: false
---

Hello World!

This is my first blog post.

NOTE:

the header part begins with 3 dashes
the draft: true meaning this file is a draft and will not be rendered into webpage (requires hugo command line $ hugo --buildDrafts=false); however if you do want to display (debug) this draft article, you can use command line $ hugo server --buildDrafts=true.
Now that the Hugo server is started, your contents will be synchronized into webpage instantly once you saved your changes.

# 1) generate the output files in ./public
$ hugo --buildDrafts=false
$ cd public

# 2) First Time: version control of the file to be published
$ git init
$ git remote add origin git@github.com:Mighten/Mighten.github.io.git

# 3) Process the changes and commit
$ git add .
$ git commit -m 'First Post: Hello World From Hugo!'
$ git branch -m master main
$ git push -f --set-upstream origin main

NOTE:

in step 2) the origin is different from person to person, please check your GitHub Settings and set it accordingly
in step 3) the upstream origin is usually named main, please go to the GitHub Pages Setting to check it.

Well Done, Now the first blog is published!