Hello World

2022-05-15 · 4 min read · Misc

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

PREPARATIONS

In this section, we will prepare the tools.

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

Toolchain

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

1$ sudo apt-get install git golang
2
3$ git config --global user.name "Your GitHub Username"
4$ git config --global user.email "Your GitHub Email"

Install `Hugo` Compiler

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:

1$ 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.

Generate RSA keys

1$ 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:

1$ ssh -T git@github.com

CREATE BLOG

In this section, we will initialize the blog.

Generate an empty site

1$ hugo new site "NewSite"
2$ cd NewSite

Initialize '.git'

This will prepare the submodule environment for Hugo themes.

1$ git init

Hugo Theme Pickup

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# 1. Getting started with Clarity theme
2$ git submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity
3
4# 2. copy the essential files to start
5$ 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.

Preview

1$ 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/

POST NOW

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

Create a new post

1$ hugo new post/post-1.md

NOTE: the folder is 'post', not 'posts'

Fill in the contents

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

 1---
 2title: "Hello World"
 3
 4description: "The first blog, and how to 'Hugo' a blog"
 5summary: "How to use Hugo to build a personal blog, and publish it onto GitHub Pages."
 6tags: ["Misc"]
 7
 8date:    2022-05-15T19:28:07+08:00
 9
10katex: false
11mermaid: false
12utterances: true
13
14draft: false
15---
16
17Hello World!
18
19This 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.

Upload

 1# 1) generate the output files in ./public
 2$ hugo --buildDrafts=false
 3$ cd public
 4
 5# 2) First Time: version control of the file to be published
 6$ git init
 7$ git remote add origin git@github.com:Mighten/Mighten.github.io.git
 8
 9# 3) Process the changes and commit
10$ git add .
11$ git commit -m 'First Post: Hello World From Hugo!'
12$ git branch -m master main
13$ git push -f --set-upstream origin main