Hugo Hextra website (1)

This static site was built using Hugo and deployed with GitHub Pages. The first blog project began with the Hextra Starter Template as the base theme. Deployment is now fully automated for seamless updates.

Hugo + GitHub Pages

Static web page

A static web page, sometimes called a flat page or a stationary page, is a web page that is delivered to a web browser exactly as stored.

— Static web page (Wikipedia)

Note

There is also a server-side or client-side dynamic web page.

Static site generator

Static site generators (SSGs) are software engines that use text input files (such as Markdown, reStructuredText, AsciiDoc and JSON) to generate static web pages. SSGs are typically for rarely changing, informative content, such as product pages, news articles, software documentation, and blogs.

— Static site generator (Wikipedia)

I just like the second place. (Ref. Static Site Generator - Ranking)

Hugo

I choose you! (Ref. Hugo)

GitHub Pages

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website.

— What is GitHub Pages? (GitHub Docs)

Hextra Starter Template

Hextra

There are many Hugo themes. Among them, I thought Hextra was the coolest name.

Let’s do great together, Hextra. (Ref. Hextra)

Use the template

I started from the bottom. Click the Use this template button. (Ref. hextra-starter-template)

Warning

I plan to keep the theme fixed to a specific version and track updates manually.

Automated Deployment

Two repository: Private & Public

Private repo	Public repo
blog sources	blog pages
Hugo source directory (`root/`)	Hugo build output directory (`root/public/`)
from Hextra Starter Template	for deployment
{Repository name}	{username}.github.io

I don’t want to open blog sources. :(

GitHub Actions

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline.

— Understanding GitHub Actions (GitHub Docs)

Note

It is helpful to read “Writing workflows” from the link above.

Deployment workflow

① Add a `deployment.yaml` File to `.github/workflows`

Delete the existing pages.yaml file and add a new YAML file (.yaml or .yml — both
extensions are acceptable).

② Generate an SSH key (in the project root directory)

Bash

ssh-keygen -t ed25519 -C "hugo-deploy-key" -f hugo_deploy_key

This generates an SSH key pair, named hugo_deploy_key (private) and
hugo_deploy_key.pub (public).

Caution

(1) GitHub Actions CANNOT use SSH keys that have a passphrase.
(2) Add the generated key files to .gitignore to ensure they are not committed.

③ Register the private key in the private repo (GitHub)

Settings > Security - Secrets and variables > Secrets > New repository secret
Copy the entire contents of hugo_deploy_key

④ Register the public key in the public repo (GitHub)

Settings > Deploy keys > Add deploy key
Copy the entire contents of hugo_deploy_key.pub & Check “Allow write access”

When I push changes to the private repo…

GitHub Actions is triggered by the push event.
The workflow checks out the private repo source code.
Hugo builds the site and generates static files in the public/ directory.
Using the SSH deploy key stored in Secrets, GitHub Actions authenticates and pushes the generated public/ output to the public repo.
GitHub Pages serves the content from the public repos as a static website.