Everywhere you write online, you’re renting. Most of the time that’s fine. I syndicate to Medium and Dev.to myself, and they bring readers my own site never would. But the platform decides who sees your work, how it looks and what the rules are next year, and none of that is yours to change. The landlord can always change the locks.
So this series is about building the place you do own: the site everything else points back to, on a stack that costs nothing and answers to nobody but you. This first part is the why and the first ten minutes, getting Hugo running on your own machine so you’ve got something to look at. Later parts put it on the internet, make it look like yours, and lock it down.
Why static, and why this stack
The site you’re reading is built with Hugo, kept in a GitHub repository, and hosted on Cloudflare Pages. Three pieces, each doing one job. Hugo turns a folder of Markdown files into a finished website. GitHub holds that folder and its history. Cloudflare Pages watches the repository, runs Hugo whenever it changes, and serves the result to the world.
The word doing the heavy lifting is static. A static site is just files, HTML, CSS, images, generated ahead of time and handed to the browser as-is. There’s no database, no server-side code running on each request, no admin login sitting on the public internet waiting to be brute-forced. Compare that to WordPress, which is a database and a pile of PHP and a plugin ecosystem you have to keep patched or watch get compromised. A static site has almost no attack surface, because there’s almost nothing running. For anyone who spends their day thinking about attack surface, that alone is a decent reason.
The other reasons are ordinary and add up. It’s genuinely fast, because serving a pre-built file from a CDN is about the quickest thing the web does. It’s free at this scale, Cloudflare Pages doesn’t charge for a personal site’s traffic. And because the whole thing is text files in git, you get version history for free, you can see every change you ever made, and nothing important lives anywhere you can’t back up with a git clone.
Three pieces, one job each. Nothing running that an attacker can knock on.
Get Hugo on your machine
Hugo is a single binary, which is part of its charm, there’s no runtime to install alongside it, no dependency tree to manage. Install it however your platform prefers: brew install hugo on a Mac, winget install Hugo.Hugo.Extended on Windows, or your package manager of choice on Linux.
One thing that catches people, so get it right now and save yourself a confusing afternoon: install the extended edition. Many themes rely on features only the extended edition has, such as SCSS processing, and the error you get when you hit that wall doesn’t say “you installed the wrong Hugo”, it says something oblique about a missing feature. The winget line above already grabs the extended build; on other platforms, check the version string after installing with hugo version and confirm the word extended is in there.
That command is also your first sanity check. If hugo version prints something, you’re ready. If it doesn’t, the install didn’t take, and there’s no point going further until it does.
Scaffold a site and see it running
Now the satisfying bit. Create a new site:
hugo new site mysite
cd mysite
That drops a folder structure in front of you, and it’s worth a five-second tour because these are the folders you’ll live in. content is where your Markdown posts go. layouts is where the templates live, the HTML that wraps your content. static is for files served as-is, and assets for files that go through Hugo’s pipeline. hugo.toml is the site’s configuration. Nearly empty for now, all of it, which is exactly why a fresh Hugo site shows you nothing when you first run it.
Run it anyway:
hugo server
Open the address it prints, usually localhost:1313, and you’ll see a blank page. That blank page is the win. It means Hugo is installed, the site is building, and the local server is live-reloading, change a file and the browser refreshes itself. You now have a working development loop on your own machine, disconnected from the internet, where you can break things freely.
It’s blank because you’ve got no content and no theme yet. That’s the next two things to sort, and it’s where the first real decision lands.
Themes, or roll your own
Hugo has a large gallery of ready-made themes. Drop one in, point your config at it, and you’ve got a designed site in minutes. For getting started, that’s a completely reasonable path, and I’d not talk anyone out of it for a first site.
I rolled my own instead, a handful of my own templates rather than someone else’s theme, and I’d gently argue it’s worth doing eventually even if not on day one. A theme is someone else’s decisions about how your site looks and works, and the day you want to change something specific, you’re reverse-engineering a stranger’s code. Your own layouts are usually simpler than a general-purpose theme, because they only have to do what your site does, not everything every site might want. That’s a later part of this series (coming soon), though. For now, if you want to see something other than a blank page today, grab a theme and move on.
Where this goes next
At this point you’ve got Hugo installed and a site building locally, which is further than most people who mean to start a blog ever get. It’s still trapped on your laptop, though, localhost is a site with an audience of one.
The next part (coming soon) takes it live: a GitHub repository as the source of truth, Cloudflare Pages wired up to build from it, your own domain pointed at it, and HTTPS handled automatically. That’s the step where it stops being a folder on your machine and becomes a place on the internet with your name on it. The place you own.
Originally published at alanconlon.com, where I post practical security, Azure and data write-ups every other Tuesday.
Top comments (0)