loading...

How to generate a static site by Hugo for GitHub Pages

callas1900 profile image r_tanaka ・2 min read

Outline

I wanted to use a static site generator instead of hand-writing html pages. I need a static site generator because I'm hosting my web page by GitHub Pages.
I decided to use Hugo because of terminal theme.
For your reference, this is steps of transfer from hand-writing to the Hugo.

Install Hugo

I'm using the linux mint and the linux brew. it works!

$ brew install hugo
...
$ hugo version
Hugo Static Site Generator v0.55.4/extended linux/amd64 BuildDate: unknown

Create a new site & Install a theme

I selected terminal theme

$ hugo new site hugo_webpage
$ cd hugo_webpage
$ git init
$ git submodule add https://github.com/panr/hugo-theme-terminal.git themes/terminal

using submodule is not mandatory.

Configuration

vim config.toml

by reading README.md

Copy from old site

I had several hand-writing html pages. Some pages were able to be transferred to Hugo markdown documents under the content/ directory, but the rest pages were not able to be done.
So that I had to use the static/ directory in order keeping the rest pages.

$ cp -R ${old_pages} static/

Confirmation

The Hugo has a serving future.
We can use this for confirmation.

$ hugo server

see also: hugo serve command

you can confirm your site with localhost:1313


trouble shooting#1

If you cannot confirm your hugo pages.
Please check again with below command

$ hugo server -D

If you can confirm the pages.
you should change your meta data of hugo markdown.

- draft: true
+ draft: false

Build it

The hugo command generates your static html pages into public directory.

$ hugo

see also: hugo command

Confirm static html server

$ cd public
$ python -m http.server 8000

Publishing

I copied everything inside the public/ directory to the repository of GitHub Pages then pushed it.

That's all.


trouble shooting#2

At Firs I attempted to create a index page for my top page beside a about page like below.

content/
├── index.md
├── about.md
...

Also my expectation of generated pages structure was like below.

public/
...
├── about
│   └── index.html
└── index.html

However the about directory was gone.
The cause is index.md. At Hugo, index.md and _index.md have special meaning.(https://gohugo.io/content-management/organization/)

Eventually I gave up creating a top page. So I created below structure.

content/
├── about.md
├── posts
│   └── hello.md
...

That's true all.

Discussion

markdown guide