Daily Grind of a Code Farmer

/home

/posts

/about

Home > Posts > Setting up personal blog: Hugo + GitHub Page + Namecheap

Setting up personal blog: Hugo + GitHub Page + Namecheap

Simple static website built on top of Hugo

  ·   4 min read

This setup is done on Ubuntu 23.10 with Intel i7-1255U

Setting up Hugo with Typo theme

  1. Install Hugo (I use v0.113.0) from here
  2. You can confirm that Hugo is properly configured by typing hugo version in the terminal
  3. Initialize the project using
hugo new site _website_ --config toml
  1. Add hugo theme, I use typo by tomfran which can be easily added by running the following commands:
git submodule add --depth=1 https://github.com/tomfran/typo.git themes/typo
git submodule update --init --recursive

The full typo wiki can be found here

  1. To add new content, create a new markdown file in content/posts with the following template
---
title: "Log-Structured Merge Tree"
date: "2023-11-12"
summary: "An LSM Tree overview and Java implementation."
description: "An LSM Tree overview and Java implementation."
toc: true
readTime: true
autonumber: true
math: true
tags: ["database", "java"]
showTags: false
hideBackToTop: false
---
  1. Start the development server using hugo server -D

Deploy Hugo website using GitHub page

  1. Conventionally, the hugo project can be built using hugo command with various extra parameters such as --gc and --minify
  2. However, I used GitHub Action as mentioned here
  3. Firstly, go to Settings > Pages and change Deploy from a branch > GitHub Actions
  4. Add the following GitHub Action yaml config to .github/workflows/hugo.yaml
# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - main

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.113.0
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb                    
      - name: Install Dart Sass
        run: sudo snap install dart-sass
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - name: Build with Hugo
        env:
          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
          HUGO_ENVIRONMENT: production
          TZ: America/Los_Angeles
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"                    
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

That’s all :) Now you just need to push it to GitHub and let the workflow runs

Configuring GitHub page with custom DNS from Namecheap

The full documentation can be found here

  1. Buy a domain from Namecheap :), I have been using this for a while and the experience is good
  2. Configure your Apex domain (i.e. the domain that is bought without www) to point to GitHub IPs by adding these 4 A records
@: 185.199.108.153
@: 185.199.109.153
@: 185.199.110.153
@: 185.199.111.153
  1. GitHub also suggests to create www subdomain, which can be configured by adding CNAME record from www to username.github.io. and GitHub will automatically redirect www subdomain to the domain.
  2. Add your custom domain to Settings > Pages > Custom domain in GitHub repo.
  3. Normally, if you are deploying from a branch, you need to create a file called CNAME containing your domain in the repo root (e.g. codefarmer.xyz). GitHub will use the CNAME file to determine which project to serve the content from. However, the FAQ, CNAME file will be ignored if the website is published using custom GitHub Action.
  4. Now, you can re-run the workflow to ensure the workflow will be publishing the site to the correct domain and wait for ~30 mins for the DNS record to be propagated.

Extra References

Sway + Ubuntu 24.04 Setting
→