Create a Personal Website With Hugo on MacOS

Introduction

This article shows how to build up a personal website using hugo and deploy it to Github Page on MacOS.

What Hugo is

Hugo is one of the most popular open-source static site generators.

Hugo can generate beautiful websites using all kinds of Hugo themes easily. Therefore, the author can focus on content creation without caring too much about the website build and maintenance.

Create Website locally

Install Hugo

On MacOS we can install Hugo using Homebrew or MacPorts.

1
2
3
brew install hugo
# or
port install hugo

You can verify your installation by checking the version of Hugo.

1
hugo version

Create a New Site Locally

1
hugo new site <your_site_name>

After running this command, Hugo will create a new folder named <your_site_name> under your work directory.

Add a Theme to Site

You can choose your own theme in Hugo Themes. After you chosen your theme, you can add it to your site in both ways.

Download the theme and unzip it into the themes directory.
Install with git submodule:

1
2
git init
git submodule add <theme_url> themes/<theme_name>

After installed the theme into your site, write theme = "<theme_name>" into the config.toml file under your work directory to implement this theme to your site.

You can now add a new post into your site with command:

1
hugo new posts/example.md

After save your changes, you can view this site locally by running:

1
hugo server -D

This command will builds and serves your site. And it will avoid writing the rendered and served content to disk, preferring store it in memory. The -D flag means include content marked as draft.

Now open http://localhost:1313/ in your browser, you should see your site with hugo theme implemented.

Create Remote Repo

You have to create a public github repo to store those static file generated by Hugo if you want to use the github page to deploy your personal website.

This new created repo must named <username>.github.io, where <username> is your username of Github. Here because I have created a repo to store my site, a duplicate name error occurs. create-repo

Deploy Site

There are two ways to deploy your site to github pages.

Build Locally and Deploy

Add the public folder (place to put static pages generated by Hugo) as a submodule of your source code folder.

1
git submodule add -b main https://github.com/<username>/<username>.github.io.git public

And change the baseURL in config.toml into https://<username>.github.io/.

Then build the Hugo pages with command:

1
hugo

Change your directory into ./public you will find those files generated by Hugo. Commit them and push the changes into the <username>.github.io repo.

1
2
3
4
cd public
git add -A
git commit -m "commit msg"
git push -u origin main

Deploy with Github Actions

In this way, we need to create a repo to store the source code of the website (This repo can be either public repo or private repo). And the source code repo will generate and deploy the static pages to <username>.github.io automatically. We can implement auto generation and deployment with the help of github workflow.

we can create a workflow in our source code repo by adding a .github/workflows/gh-pages.yml file to it. The content of this file refer to Hugo Setup is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
name: github pages

on:
  push:
    branches:
      - main  # Set a branch to deploy

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          # extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          external_repository: <username>/<username>.github.io	# which repo to be deploy to
          personal_token: ${{ secrets.ACTION_ACCESS_TOKEN }}	# personal_access_token is needed if you want to publish content to other repo
          publish_dir: ./public	# which folder of the source code repo to be deployed. Because hugo generate its static pages into public folder, publish_dir is ./public
          publish_branch: main	# which branch of target repo to publish to

You can generate ACTION_ACCESS_TOKEN by clicking your avatar right-upper side. And in Settings->Developer settings->Personal access token you can generate a new token.

Generate a token with repo, workflow and admin:repo_hook selected, and save the token for next step. gen-access-token Now that you’ve got the access token, go to the source code repo to set up the secrets.ACTION_ACCESS_TOKEN.

Create a new repository secret inside the Settings->Secrets of your source code repo. Name it as ACTION_ACCESS_TOKEN and paste the token we get above here.

Now the github workflow will do the auto deployment for you once you push new commits to the source code repo.

Congratulate! You can see your website if you type <username>.github.io in your browser now 👏

Reference

Hugo

Github Pages

Hugo Setup

Table of Contents