I'm not a developer by trade. I'm an SEO content writer, and my portfolio site was the first real "build" I owned from scratch, no template, no agency, no dev friend doing it for me. So when it came time to pick a stack, I went through the exact debate a lot of people have in their first project: hand-rolled HTML, or a static site generator?
I tried both. I ended up shipping pure static HTML. Here's the reasoning, and where it started to hurt.
Where I started: one HTML/CSS file
The first version of the site was literally a single index.html with inline <style>. No build step, no node_modules, no config file to get right before I could see anything on screen. I opened the file, wrote markup, refreshed the browser. That loop was the whole point: I wanted to spend my mental energy on content and design decisions, not on debugging a bundler.
It grew from there into three pages (index.html, apropos.html, cas-clients.html) sharing the same design system: CSS variables for colors and type, the same nav, the same footer, copy-pasted at the top and bottom of each file.
Then I needed a blog, and Eleventy looked like the obvious answer
Three static pages, fine. But a blog is a different problem: every new post needs the same header, the same nav, the same footer, the same article-card markup on the index page. That's exactly what a static site generator exists to solve. I looked seriously at Eleventy ā shared layouts, a posts collection that auto-builds the index, front matter instead of hand-editing HTML for every publish.
On paper it was the right tool. In practice, I stepped back.
Why I didn't go with Eleventy
A few reasons, roughly in order of how much they actually mattered:
- I wasn't going to publish at a volume that justified the overhead. A handful of articles a month, not a content site pushing dozens of posts a week. The maintenance cost of a templating layer only pays for itself past a certain publishing cadence, and I wasn't there.
- Every dependency is something that can break during a deploy, and I'd have to debug it without deep Node tooling experience. Static HTML fails in exactly one way: you wrote something wrong in the file. An SSG build can fail for reasons that have nothing to do with your content.
- I wanted zero ambiguity about what actually ships. With plain HTML, the file in the repo is the file the browser renders. No templating logic sits between what I wrote and what's live, which matters a lot when SEO details (title tags, meta descriptions, canonical URLs) need to be exactly right on every single page.
- Migrating hosts stays trivial. I moved the whole site from Netlify to Cloudflare Pages recently after hitting Netlify's free-tier build-credit limit. Because there's no build step, that migration was: point the new host at the same repo, done. No adapting a build config to a different platform's quirks.
How the blog actually works without a templating system
No system means the process is manual, and I made that explicit instead of pretending otherwise. There's a literal comment block at the top of the article list in blog/index.html:
<!--
To add a new article:
1. Create an HTML file in /blog/ (e.g. /blog/my-article.html)
2. Copy-paste an <a class="article-card"> block above
3. Update the date, title, link, description, and thumbnail
No templating system is used here: every article is a self-contained HTML file.
-->
Each article page is a full standalone file that reuses the same CSS variables and layout structure as the others, copied from the last one I wrote and edited in place. It's not elegant. It's honest about what it is.
Where this actually costs me
I won't pretend there's no trade-off:
- Updating the nav or footer means touching every single HTML file, not one
_layout.html. - There's no automatic index generation: adding a post to the blog listing is a manual copy-paste, and it's on me not to forget the thumbnail or get a date wrong.
- If I ever publish fast enough that markup drift between article pages becomes a real risk, this stops being the right call.
That last point is the actual answer to "static HTML or a generator": it's not a permanent philosophical stance, it's a decision that's correct at a specific scale and wrong past it. I know roughly where my ceiling is (probably somewhere around "I can't keep the last three templates straight in my head anymore"), and I'll reach for Eleventy, or something like it, when I hit it.
The site, as it stands
It's live here: mon portfolio, running on Cloudflare Pages, zero build step, every page a plain HTML file.
Curious where others draw this line. If you've made the jump from hand-rolled HTML to an SSG, what was the actual trigger ā a specific pain point, or just a rule of thumb about post count?
Top comments (0)