I started this repo because I wanted a place to publish projects. That was the whole brief.
Built the first version of the portfolio, pushed past the starter-template stage, and turned an initial Zola site into the beginning of a custom publishing system.
The less tidy version is that I felt a real pressure to start accumulating visible work. I had the pretty common realization that if I wanted a body of writing and project history later, I had to start building it before it felt complete.
The first commit landed on 2019-08-31 with the message Building initial static site with zola. That was me taking the boring first step instead of waiting for a perfect system.
The earliest shape of the repo was straightforward:
design/design.xdThat part moved quickly because it was meant to move quickly. I was not trying to solve the entire publishing problem. I was trying to stop having no public home for my work.
The next few commits show the first friction pretty clearly:
Adding more inter-content linkingVendoring mini.css 3.0.1 with default flavorRemoving default theme, auto-formatting htmlVariabialize colors, strip classesSwitching to every layout, first bitsThat is a pretty reliable pattern in my projects: I start with the default path, then almost immediately run into a “this is not shaped right” problem.
Zola itself was not the enemy here. The problem was that I wanted more direct control over theming and layout than the starter shape was giving me.
Customization was the annoying part.
The repo shows that through vendored CSS and repeated layout edits. I pulled mini.css into the repo instead of treating styling as a black box. Later I started switching toward Every Layout ideas because I wanted more predictable primitives instead of one-off page styling.
That early styling work is visible in files like:
site/sass/mini.scsssite/templates/base.htmlsite/mini.css/_core.scsssite/mini.css/_layout.scssThe details changed, but the reason was stable: I wanted a design that felt sparse, legible, and under control.
One thing the history understates is how much time went into the layout system.
I spent a lot of time on fluid and algorithmic layout behavior. Part of that was aesthetics. Part of it was practical. At that point I did not have a huge amount of content, so a very clean and sparse design helped avoid making the site feel empty in an embarrassing way.
More importantly, Every Layout clicked with how I wanted to work. It made site building feel predictable.
The practical lessons were pretty immediate:
That mattered because I was already trying to avoid one-off styling decisions. I wanted layout primitives I could reuse without having to renegotiate the whole design every time I added content.
I did not leave Zola because it was bad. I left because it was pretty clear I was going to want:
I was already familiar with React, and Gatsby looked like the more expandable path.
The trade-off was pretty clear to me even then:
That is why the October 2019 Gatsby hello-world commit is such a big turning point. The subject line is funny in hindsight because it represents a full framework migration. The scope of that move was much larger than the wording suggests.
I did not arrive with a grand Gatsby master plan.
It was closer to: I think this stack will let me get where I want to go, so let me prove that before I overthink it.
That is why the transition into the first Gatsby commits feels pretty direct in git. Once the Zola path started feeling constraining, I was willing to jump to a better substrate rather than spend a long time making the original choice slightly less wrong.
You can see the new center of gravity immediately in the files added around the Gatsby migration: React page entrypoints, Gatsby config, and the beginning of a component-driven layout system.
The migration itself was not exotic, but it was concrete: port the entry pages, move the layout logic into React components, re-establish global styling, and then rebuild the publishing behavior on the new substrate instead of trying to preserve the old theme structure.
Later on that evolved into the page-generation and frontmatter validation code that took over the repo:
export function isMarkdownCommonFrontmatter(o: unknown): o is StringRecord {
if (!isStringRecord(o)) {
throw new FrontmatterError("Missing frontmatter")
}
if (typeof o.title !== "string") {
throw new FrontmatterError("Missing title")
}
if (!isISODateTimeString(o.date)) {
throw new FrontmatterError(
`Invalid date format, expected ISO date got ${o.date}`
)
}
That snippet is from the modern src/gatsby/create-pages.ts, not the first migration commit, but it shows the direction the repo was moving toward: more explicit structure, more validation, less hand-wavy content plumbing. I left it in here because that is the real lesson of the migration: the framework change only mattered because it gave me a better place to put the rules I was clearly going to need.
The useful result of the Zola phase was not the site itself.
It proved two things:
That second point matters. A lot of the rest of this repo follows from it.
I have a pretty strong intolerance for environments that fight back ergonomically. If the structure feels wrong, it keeps bothering me until I either fix it or route around it. That can be expensive in time, but it also explains why the repo kept evolving instead of freezing into a starter template forever.
The earliest era of this repo is not the most technically impressive part, and that is fine.
Its job was to establish momentum, then reveal the first real constraint. Once it became obvious that I cared more about control, layout primitives, and future flexibility than I cared about preserving the original stack choice, the Gatsby migration became the natural next move.
That is where the project stops being “a website I spun up” and starts becoming infrastructure for the kind of writing I actually wanted to do.