This is the first part in a series of blog posts about setting up this website with Hugo. In this part, I cover setting up the development environment: from installation to a running local site.
Why Hugo?
There are dozens of static site generators available, but Hugo stands out for its speed. The site builds in milliseconds, and the built-in dev server reloads the page instantly on every change. No Node.js runtime, no bundlers, no waiting — just fast builds.
Additionally, Hugo offers out-of-the-box support for multilingual sites, which was a must for this site (Dutch and English).
Installing Hugo
On Windows, the easiest way is via Chocolatey:
choco install hugo-extended
On macOS via Homebrew:
brew install hugo
Then verify that everything is set up correctly:
hugo version
I use the extended version of Hugo. This is required if you want to use SCSS/SASS or other asset processing via Hugo Pipes.
Creating a new project
With Hugo, creating a new project is a single command:
hugo new site my-site
cd my-site
This generates the following directory structure:
my-site/
├── archetypes/ # Templates for new content
├── assets/ # Files processed by Hugo Pipes (CSS, JS)
├── content/ # All site content (Markdown)
├── data/ # Data files (JSON, YAML, TOML)
├── i18n/ # Translations
├── layouts/ # HTML templates
├── static/ # Static files (images, fonts)
├── themes/ # Themes
└── hugo.yaml # Configuration file
The two most important directories to remember: content/ for your text and layouts/ for your templates.
Choosing a theme
Hugo has a large theme library with ready-made Hugo themes. For this site, however, I chose a different approach: I started with the Simple Portfolio Template, a pure HTML/CSS/JS template that was not specifically made for Hugo. I then manually converted this template into a Hugo theme by splitting the HTML into Hugo layouts and partials, and moving the assets to the correct directories.
The advantage of this approach is that you’re not limited to existing Hugo themes — any HTML template can serve as a starting point. It takes a bit more work to convert, but you have full control over the end result.
Do pay attention to the license of the template you use. Many templates use an MIT license, which means you can freely modify and use them, as long as you include the original copyright notice and license. Keep the LICENSE file in your theme directory to comply.
Place a theme in the themes/ directory and activate it in hugo.yaml:
theme: theme-name
Configuration
The heart of every Hugo project is the configuration file. I use hugo.yaml (Hugo also supports TOML and JSON). A minimal configuration looks like this:
baseURL: https://your-domain.com
title: My Site
theme: theme-name
Later you’ll add parameters for metadata, social links, and language settings. But for now, this is enough to get started.
The local dev server
This is where Hugo truly shines. Start the development server:
hugo server
Your site is now available at http://localhost:1313. Every change you save is immediately visible in the browser — without manually reloading. This makes the development process extremely pleasant.
Want to see draft posts as well? Use:
hugo server -D
Setting up Git
A Hugo site is just a directory with files, which makes it perfect for version control with Git. A few tips:
- Add a
.gitignorewith thepublic/directory (this is regenerated on every build) - The
resources/_gen/directory is Hugo’s cache for processed assets (such as compiled SCSS or resized images). It is automatically created when needed, so it can be excluded as well - Commit regularly, so you can always go back to a working version
public/
resources/_gen/
.hugo_build.lock
Claude Code as a tool
When setting up this site, I used Claude Code as an AI assistant. Especially when setting up the project structure, writing templates, and debugging CSS, this was an enormous time saver. Claude Code understands the Hugo structure and can work directly in your project via the terminal.
A CLAUDE.md file in the root of your project helps Claude Code understand the context of your project — which commands you use, how the architecture is structured, and which conventions you follow.
Next step
In the next part, I’ll show how I converted the HTML template into a fully working Hugo theme — from splitting the HTML into layouts and partials to setting up Hugo Pipes for CSS and JavaScript.
