Building My Own Tech Blog with Hugo and Vercel: A Complete Setup Guide and Troubleshooting Report

I've finally launched my personal tech blog, Rico's Tech Blog (ricosheaven.com), to the world! I started out with the combination of Hugo, a lightweight, fast static site generator (SSG), and Vercel, an automatic deployment platform, and went through a mountain of technical debugging along the way, from the initial environment setup all the way through to a completed deployment.

In this write-up, I'm documenting the entire process I went through today — building a Hugo blog from scratch and deploying it to Vercel — along with the solutions to all the roadblocks I hit along the way, in one single guide.

1. Setting Up the Local Development Environment & Creating the Hugo Site

The first step was to create a Hugo site in my local Mac environment and apply PaperMod, the most widely used blog theme. To prevent the build from breaking due to Git submodule path issues during Vercel deployment, I set it up so the theme is included as a "regular folder" instead of a submodule.

# 1. Create a new blog project folder and move into it
mkdir my-blog && cd my-blog

# 2. Create the Hugo site
hugo new site . --force

# 3. Clone the PaperMod theme and strip its submodule metadata (turn it into a plain folder)
git clone https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
rm -rf themes/PaperMod/.git

# 4. Keep Git from tracking these (set up .gitignore)
echo "/public/" >> .gitignore
echo "/resources/" >> .gitignore
echo ".hugo_build.lock" >> .gitignore

2. Writing the Blog Configuration File (hugo.yaml)

To define the blog's title, language, and theme settings, I wrote a hugo.yaml configuration file at the project root.

baseURL: 'https://ricosheaven.com/'
languageCode: 'ko-kr'
title: "Rico's Tech Blog"
theme: 'PaperMod'

params:
  env: production
  title: "Rico's Tech Blog"
  description: 'IT 개발 및 지식 기록 공간'

  homeInfoParams:
    Title: "안녕하세요!"
    Content: "IT 개발 및 기술 지식을 기록하는 공간입니다."

3. Writing the First Post and Pushing to a GitHub Remote Repository

After writing a test post markdown file (content/posts/first-post.md), I created a new repository on GitHub and pushed the source code.

# Create a test post
hugo new posts/first-post.md

# Initialize Git and commit
git init
git branch -M main
git add .
git commit -m "Initial commit - Fresh Hugo setup"

# Connect the GitHub repository and push
git remote add origin https://github.com/Rico83-KR/my-blog.git
git push -u origin main --force

4. Deploying to Vercel and Connecting a Custom Domain

I connected the GitHub repository in the Vercel dashboard to set up an automatic deployment pipeline.

1. Click Vercel Dashboard ➔ Add New... ➔ Project
2. Import the my-blog repository from GitHub
3. Select Hugo as the Framework Preset, then run Deploy
4. Once the deployment succeeds, go to Settings ➔ Domains and connect the custom domain (ricosheaven.com)

5. Trial and Error, and Troubleshooting

Here I've summarized the most critical problems I ran into while building the blog, along with their causes and how I fixed them.

Issue 1 A Typo in a Config Key and the public Folder Being Tracked by Git

Symptom: Even after editing the hugo.yaml file and committing, the main title change wasn't reflected on the remote deployment.

Cause: I had typed tiltle: instead of title:, and on top of that, the local build output folder /public/ had been committed to Git, so Vercel kept serving only the old static files.

Fix: After correcting the typo, I forcibly removed the public folder from Git's tracking list.

git rm -r --cached public
git commit -m "Remove public build files from tracking"
git push origin main

Issue 2 After Deploying to Vercel, Only the Bare "Recent content on Hugo" Screen Shows Up

Symptom: The Vercel deployment status showed Ready, but the PaperMod design wasn't applied at all — the page just displayed a white background with the text Recent content on Hugo -- gohugo.io.

Cause: Vercel's default Hugo builder engine version was pinned to an old release, so it failed to parse the templates of the latest PaperMod theme.

6. Closing Thoughts

This started out as a lighthearted static blog build, but it turned into a real lesson in just how important it is to keep engine versions in sync between the local development environment and a cloud CI/CD build server, and to manage what Git tracks carefully.

Now that every part of the environment lines up perfectly and the site is deployed, I'm looking forward to steadily filling this space with notes on algorithms, troubleshooting, and whatever new technologies I pick up along the way!