From Empty Jekyll Site to Something That Actually Feels Like Mine

Categories: jekyll, css frameworks, design system

I started this blog the same way a lot of side projects start: with a clean Jekyll scaffold, a vague aesthetic target, and the dangerous confidence that I could “just wire it up in an afternoon.”

The early version was intentionally simple. I added Water.css, got a basic layout in place, and had pages rendering quickly. It worked. It was readable. It was also generic in exactly the way a first pass usually is.

Then the real work started.

The shift from “site exists” to “site has structure”

The first meaningful improvement was URL and content structure.

I wanted posts to live under a dedicated namespace instead of hanging off root-level routes, so I moved to a /posts/:title/ pattern. It seems small, but this is one of those decisions that quietly pays off later. Your URLs become more predictable, your content model is clearer, and your site starts to feel like an actual publication instead of a pile of pages.

From there, discovery became the next concern. I didn’t just want writing to exist, I wanted it to be browsable. Categories became the primary organizing system, and I initially explored manual category pages before switching to plugin-based generation for scale. Manual pages are fine at first; they become friction as soon as you stop having “just a few posts.”

That pivot was one of the bigger themes of this build: moving from “works now” to “still works after I publish 50 more posts.”

Homepage semantics, not just styling

Once structure was solid, I reworked the homepage to show a real post feed: latest entries, short summaries, semantic markup, and cleaner separation of concerns between content and layout.

I learned (again) that presentation logic dumped into markdown gets messy fast. Moving feed rendering into the layout gave me cleaner templates, better semantics, and fewer weird rendering edge cases.

This site stopped feeling like a static landing page and started behaving more like a blog.

Developer experience matters on a solo blog too

I spend enough time in code blocks that syntax highlighting quality was non-negotiable. So I integrated Rouge styles with both light and dark variants, and then documented lexer/language support so future me doesn’t have to rediscover what’s already available.

I also added styled markdown callouts for notes, warnings, and tips. This was one of those tiny quality-of-life upgrades that disproportionately improved readability. The first version looked too much like default blockquotes, so it got refined until callouts were visually distinct without feeling loud.

There’s a pattern here: almost nothing was “one and done.” Most things got better on the second or third pass.

Visual identity: the site finally got a face

The masthead was where the blog started to feel personal.

I added a home-only hero section with a gradient treatment and profile image, then refactored it to be config-driven instead of hardcoded. That gave me flexibility to adjust tone and messaging without touching layout code every time.

Navigation went through multiple iterations too. Fixed versus sticky behavior, mobile dropdown readability, spacing, contrast, active-state clarity. These weren’t dramatic redesigns. They were small, cumulative improvements that made the interface feel intentional.

The part no one posts screenshots of: production debugging

The hardest part wasn’t writing templates. It was making local and production behave the same.

At one point, the site looked right locally but wrong after deploy. The only way through was to stop guessing and compare generated artifacts directly: built HTML, compiled CSS, live output, and asset URLs.

That surfaced real issues:

• stale CSS from caching
• mobile viewport quirks caused by 100vw breakout techniques
• layout regressions introduced while fixing another responsive issue
• route-specific wrapper differences that affected spacing on posts vs home

Each fix was straightforward in isolation. Together, they were a good reminder that frontend systems fail at the seams, not usually in the obvious center of a component.

What this process actually changed

By the end, I didn’t just have a prettier theme. I had a blog foundation that is:

• structurally cleaner (URL and archive model)
• easier to extend (config-driven sections and plugin-backed archives)
• more readable (semantic feed, callouts, code styling)
• more stable across breakpoints and routes
• less fragile in production (cache strategy and artifact-level validation)

In other words: less “demo,” more “system.”

Final thought

I started with an empty Jekyll site and a CSS framework. I ended up with something that feels authored, not assembled.

Most of the value came from iteration, not from any single big feature. Small choices around structure, semantics, and debugging discipline compounded into a site I actually want to keep publishing on.

And honestly, that was the goal the whole time.