Implementing This Site

Choosing and Customizing the Theme

I started my Hugo website by selecting the Terminal theme, known for its clean and modern design. However, rather than using the theme directly, I decided to leverage its codebase to create a fully custom site that better suited my needs. Here’s how I did it:

Cloning the Theme of your choice:

I began by cloning the Terminal theme files into my Hugo project:

git clone https://github.com/panr/hugo-theme-terminal.git themes/terminal

Extracting the Theme Code:

Next, I copied & extracted the essential files and directories from the theme into my project files accordingly:

cp -r themes/terminal/layouts layouts/
cp -r themes/terminal/static static/
cp -r themes/terminal/assets assets/

Customizing the Site:

With the theme’s layouts and assets now part of my project, I customized the site’s look and feel by editing the layout files and adding my unique content.

Building and Testing Locally

To ensure everything works perfectly, I often build and preview the site locally - which i recommend doing before pushing:

Building Drafts Locally:

During development, I include drafts in the build to preview all content:
```
hugo server -D
```
The -D flag includes draft content (draft: true in front matter) in the local build.

Using Hugo Logs for Error Detection:

To catch any errors or warnings during the build process, use the Hugo’s logging options:
```
hugo --log --logFile hugo.log
```
This command generates a hugo.log file that captures all logs, helping to identify and resolve issues like missing partials or incorrect configurations.

Pushing to GitHub and Setting Up GitHub Pages

To deploy the website, I used GitHub Pages. Here’s the step by step process I followed:

Initializing Git and GitHub Repository:

I initialized the Git repo in my project directory and pushed it to GitHub:

# 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:

# Set the 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 you 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.128.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

 # The 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

Setting Up GitHub Actions:

To automate the deployments, set up a GitHub Actions workflow. My .github/workflows/deploy.yml looks like this:

name: Build and Deploy The Hugo Site

on:
 push:
  branches:
    - main

jobs:
 build:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v2
    - name: Setup Hugo
     uses: peaceiris/actions-hugo@v2
     with:
      hugo-version: '0.115.2'
    - name: Build
     run: hugo
    - name: Deploy
     uses: peaceiris/actions-gh-pages@v3
     with:
      github_token: ${{ secrets.GITHUB_TOKEN }}
      publish_dir: ./public

Using a Custom Domain:

I configured a custom domain for my GitHub Pages site, which involved several steps:

Configuring the Custom Domain

Setting the Domain in GitHub Pages:
- In the repository settings under the “Pages” section, I set the custom domain to mycustomdomain.com.
Adding a CNAME File:
- I added a CNAME file to the static directory with the content:
```
mycustomdomain.com
```
- This file ensures that GitHub Pages knows to serve the site under the custom domain.

Verifying the Domain and DNS Configuration

Domain Verification:
- To verify my custom domain, I needed to add a DNS TXT record provided by GitHub to my domain’s DNS settings. This record helps GitHub verify ownership of the domain.
DNS Records Setup:
- A Records:
- I pointed the domain(or if you have multiple domains) to GitHub Pages by setting A records for the root domain (@) to the following IP addresses:
```
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
```
- These IPs are GitHub’s server addresses.
- CNAME Record:
- For the www subdomain, I added a CNAME record pointing to username.github.io, replacing username with my GitHub username.

Configuring Hugo

baseURL: 'https://website.com/'
languageCode: 'en-us'
title: 'My Site'
timeZone: "America/Los_Angeles"
menus:
  main:
    - identifier: about
      name: About
      url: /about
      weight: 20
    - identifier: blog
      name: Blog
      url: /blog
      weight: 30
    - identifier: tags
      name: Tags
      url: /tags
      weight: 40
paginate: 10
permalinks:
  blog: "/blog/:year/:month/:day/:title/"
taxonomies:
  tag: "tags"
  author: "authors"
indexes:
  tag: "tags"
markup:
  defaultMarkdownHandler: "goldmark"
  goldmark:
    # Enable or disable smartypants (automatic conversion of ASCII punctuation to smart punctuation)
    smartypants: true
    # Enable or disable fractions (automatic conversion of fractions)
    fractions: true
    # Enable or disable superscript and subscript support
    # (enable to allow ^ and ~ for superscript and subscript)
    superscript: true
    unsafe: true
outputs:
  section:
    - HTML
    - RSS
    - sitemap-blog.xml
  home:
    - HTML
    - RSS
    - sitemap.xml
params:
  social:
    - name: github
      url: https://github.com/myusername
    - name: x
      url: https://x.com/myusername
    - name: youtube
      url: https://youtube.com/username
    - name: linkedin
      url: https://linkedin.com/in/username

module:
  hugoVersion:
    extended: false
    min: "0.116.0"

📝 Implementing This Website