Hugo Static Website on GitHub Pages

Hugo can be installed with the use of package managers (i.e. brew, choco, pacman). The option to build from source or run on docker are also available; check out the install guide for details.

In my case, I can find hugo via pacman using the CLI.

pacman -Ss hugo

community/hugo 0.92.0-1 [installed: 0.89.4-1]
    Fast and Flexible Static Site Generator in Go

Validate the hugo install by checking the version.

hugo version

hugo v0.89.4+extended linux/amd64 BuildDate=unknown

Navigate to your preferred working directory and create the hugo site; I'm calling this site example.

hugo new site example

Navigating into the directory, we see that Hugo has created content for a basic hugo site.

cd example
tree . -L 1

example/
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── resources
├── static
└── themes

8 directories, 2 files

Optionally, initialize a git repository for this project; the repository used for GitHub pages will be managed separately.

git init

Free themes for Hugo are available at themes.gohugo.io and many other websites.

Find any particular theme and either clone the theme repository or add it as a submodule under example/themes.

git submodule add -f https://github.com/panr/hugo-theme-terminal.git themes/terminal

The primary file used to configure Hugo is config.toml. Update the file to define the corresponding theme to be used.

baseURL = "https://www.example.com"
languageCode = "en-us"
title = "Example"
theme = "terminal"

Additional Hugo site configurations can be made based on the theme selected. For an example site based on your theme, check out themes/<name>/exampleSite (if it exists).

tree themes/terminal/exampleSite -L 1

example/themes/terminal/exampleSite
├── archetypes
├── config.toml
├── content
├── data
├── deploy.sh
└── resources

4 directories, 2 files

The website pages are managed under example/content. To create a new blog post, create a file manually under example/content/posts/; hugo supports both markdown and org documents (hooray, emacs!).

Alternatively, initialize the post with hugo from the CLI to include the metadata headers.

hugo new posts/hello-world.md

Run the hugo server and include draft documents when serving. By default, the site can be accessed via a web browser on localhost:1313.

hugo server -D

On GitHub, create the repository used to serve the GitHub pages and name it based on your GitHub username (username.github.io).

For example, jessemolina.github.io; visit pages.github.com for more details.

Once the repository has been created, add the new repository as a submodule under the public directory - this will host the static files required to generate the website.

git submodule add https://github.com/jessemolina/jessemolina.github.io.git public

To generate the static files into the public directory, run hugo with theme flag. This command will need to executed each time a change is made or new content is created.

hugo -t terminal

Looking at public, we can see the populated content.

tree public/ -L 1

../../public
├── about
├── categories
├── css
├── images
├── index.html
├── index.xml
├── js
├── lib
├── posts
├── sitemap.xml
└── tags

8 directories, 5 files

Change directories, git commit and push to the remote username.github.io respository.

cd public
git add .
git commit -m 'init commit'
git push

After a few minutes, the website should be available online at username.github.io.

If you have a custom domain name, you can add GitHub's DNS records through your domain name service provider. Check out the github documentation for more details on how to configure pages to use your custom domain name address.

Thanks for reading.