Building My Hugo Site from Scratch — And Breaking It Along the Way

May 21, 2025

building my hugo site

All I wanted a fast, clean personal website. Something I had full control over and could actually understand. I was frustrated with using pre-made themes that were often bloated and I had no idea how to configure.

I started with a simple index.html page and styling it with a little CSS and added some Javascript to make things like the hamburger menu work on mobile devices. It looked really good and was super fast and responsive, but I realized that if I needed to add pages or make a change to the navbar, it might take all day to update my site by hand.

Like most programmers, I am naturally lazy and figured there had to be a better way to do this. I wanted to spend less time updating my site and more time working on projects. I should be able to automate most of this without resorting to using Wordpress for my site.

That led me to Hugo, a static site generator that lets you build performance-first sites using plain HTML, CSS, and Markdown. Easy to add a post and if you need to make a change to the footer or nav-bar, it takes like 2 seconds and the entire site is updated.

Very cool.

But I really didn’t know much about Hugo before I started this project, and while the learning curve was pretty steep at first (especially if you are building your own theme) I will never go back to building sites the old-fashion way again.

This post isn’t a tutorial though. It’s a recap of what actually happened while I built this site — the wins, the bugs, and the “why is my footer hovering in the void?” moments.

What I Set Out to Build

  • A custom Hugo theme that looked like a real site
  • A responsive layout that worked across desktop and mobile
  • A blog section that was easy to update and visually clean
  • Navigation that didn’t break on mobile (harder than you’d think)

What Broke (and How I Fixed It)

  • Pages randomly vertically centered: Turns out I was applying .hero classes to every page. Oops. Fixed by scoping layout logic to just the homepage.
  • Footer overflowed and blocked links: Found out a gradient pseudo-element was catching mouse events. pointer-events: none saved the day — or just removing it entirely.
  • Blog post layout clashed with my About page: Solved it by conditionally adding different classes to blog posts vs. standalone pages using {{ if eq .Section "blog" }} in the single.html layout.
  • Links turning purple: Browser defaults are wild. Reset with a quick a:visited { color: inherit; }.

What I Learned

  • Hugo is powerful, but you need to understand how templates inherit and cascade.
  • Flexbox and page height will mess with your layout if you’re not careful.
  • Small details matter — getting the spacing, type, and structure right took work, but now the site feels like mine.
  • Sometimes the fix is just… trying things. The bug I spent hours on was fixed by removing one word from a class. That’s dev life.

What’s Next

I’ll be fleshing out more pages, getting my first few real blog posts live, and automating deployment so I can push updates with a single script. If you’re curious how it works under the hood, I’ll be posting more Hugo tricks soon.

This project was a win. Not because it was perfect, but because I built it, broke it, and fixed it — and now it’s running live, fast, and it’s my creation.