Publish a static blog created by Hugo on GitHub Pages

 Posted on August 11, 2020  |  Kenji Arai

Motivation

I had been thinking of the place to compile and store some researches and trials I had done on my field of interest. I decided to use mark downs to describe them, because I’d like to be able to rerecence pages on the internet, display source files such as shell script, and even express formulas.

When I was thinking about it, GigHub comes to mind and I decided to store and publish it on GitHub Pages.

GitHub Pages is a web hosting service for static web pages that GitHub provides to its users. (From Wikipedia) I

With thanks to the reference pages

This page. Thanks.

Furthermore, I also consulted this page. Thanks as well.

You should think about what kind of page you want it to be before you start working on it, and think about what theme you want it to be about with reference to this page.

Client Environment

My Client environment is as follows.

  • MacBook Pro（2016）
  • macOS Catalina version 10.15.6

Creating a repository for GitHub Pages

First of all, prepare a destination repository. This section should be done on browser.

It is assumed that you already have a GitHUb Account. If you search for “GitHub account creation”, you can find a number of pages.

Create a repository for GitHub Pages in the following steps.

  • Sign in to GitHub and go to “Your repositories” (at the top level).
  • Click on the “New Repository” menu in the upper right corner to create a new repository
  • Enter the following on the “Create a new repository” page
    • Repository name: foo.github.io (where foo is your account name)
    • Others remain in default.
    • Create repository with “Create repository”.

Install Hugo, create a hugo project

From here, we’re going to work in a Mac terminal.

In the following steps, install hugo and create a project (in this example, a directory with a blog) to work with.

$ brew install hugo
$ cd ~/workspace
$ mkdir blog
$ hugo new site blog

Initializeing the git repository and selecting a theta

I have chosen a simple theme called “beautifulhugo” for myself. The following is assumed this theme.

$ git init
$ git submodule add https://github.com/halogenica/beautifulhugo.git themes/beautifulhugo
$ cp -r themes/beautifulhugo/exampleSite/* .
$ hugo server

Check the theme on local environment

Now that you have started the hugo server, browse the theme in your local environment (in my case, Mac’s browser).

  • In the browser, type"http://localhost:1313/”.

Check the various pages and think about how to change it as yourself. Once you’re done checking, on the terminal (typed “hugo server” above), use “CTRL+C” to exit the hugo server.

Edit the configuration file (config.toml)

The file config.toml is used to set up a static site for hugo.

You should edit it with an editor such as vim.

In my case, I changed the following points.

  • I added [languages] because I’m thinking of preparing both Japanese and English languages. See Beautifule Hugo for instructions on how to put them in config.toml.
  • For the actual pages in Japanese and English, make jp and en directories under the content directory, and prepare page and post directories in each of them.
  • The page displayed by “ABOUT” in the upper right corner of the sample page should be described by “about.md” under the post directory. In Japanese, it is ~/workspace/blog/content/jp/post/about.md.
  • Blog posts are stored in the post directory by markdown (.md). If the blog post is hoge.md, it is ~/workspace/workspace/blog/content/en/post/hoge.md.
  • At the top of the post, if you insert the lines “tilte:”, “date:”, and “tag:” with only “—” at the beginning of the post, you can add Title, date, etc. can be referenced. See the sample article (.md file) on the theme. It’s called YAML front matter, and can be used in TOML.
  • The “samples” on the upper right, which I checked in the sample page, is not used for the time being, but in the future, it seems to be useful so that you can see carefully selected articles, etc. immediately.

Association with GitHub Pages

Associate your local repository with a remote (GitHub Pages) in the following way:

$ git remote add origin https://github.com/akenji3/blog
$ git submodule add -b master https://github.com/akenji3/akenji3.github.io public

If there is a pubulic directory in local when you do “git submodule add” above, you get the following error.

So, do the above before creating a static page on hugo locally.

'public' already exists and is not a valid git repo

Deploying to GitHub using shell scripts

Create a file, deploy.sh, with the following contents and grant the right to execute it. By this shell pro, deploy a static page to GitHub Pages.

#!/bin/sh

# If a command fails then the deploy stops
set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`

# Go To Public folder
cd public

# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
	msg="$*"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

Store the written article in the given directory and do the following. If you have a shell pro in the current directory.

$ ./deploy.sh

What I noticed

Here’s a list of things I’ve noticed. Only one thing now. I’m a little worried about this one.

  • If the file name of the blog post is hoge.md and the hoge contains Japanese, GitHub Pages will post the summary at the top, but when you go to “read more” from there to view the page, you get a 404 error.
GitHub Pages  Hugo