This post is part of a series on my process and progress building out this site from a plain portfolio page into something that can actually hold writing, projects, and whatever else I decide belongs here.

In Part 1 I wrote about the fun part: adding Eleventy, turning Markdown into article pages, building an articles index, and making the site feel a little more like a real place for writing.

This post is about the less glamorous part.

The part where everything technically works locally, gets uploaded, and then immediately acts like it has never seen a stylesheet before.

So, naturally, this is the more useful post.

The subfolder problem

My site is not hosted at the root of a domain. It lives here:

drgiddens.com/mcgowen/

That detail matters more than I wanted it to.

When a site is hosted at the domain root, this path works fine:

/assets/img/article/fullsize/article1.png

The browser reads that as:

drgiddens.com/assets/img/article/fullsize/article1.png

But my files are not there. My files are here:

drgiddens.com/mcgowen/assets/img/article/fullsize/article1.png

That means a root-relative path like /assets/... is quietly wrong.

Not obviously wrong. Quietly wrong. The worst kind.

Locally, it can look fine because the development server is serving the project from the root:

localhost:8080/

But once the same site is uploaded under /mcgowen/, the path points to the wrong place.

This is the kind of problem that makes you briefly consider becoming a carpenter.

Root-relative versus relative paths

The fix was to stop assuming the site lived at the domain root.

Instead of this:

<link href="/css/styles.css" rel="stylesheet" />

the homepage can use this:

<link href="css/styles.css" rel="stylesheet" />

The articles index lives one folder deeper, so it needs:

<link href="../css/styles.css" rel="stylesheet" />

And an individual article page lives two folders deep:

articles/gods-and-snakes-part-1/

So it needs:

<link href="../../css/styles.css" rel="stylesheet" />

That is not beautiful. But it is understandable.

The basic rule became:

Where is this page after Eleventy builds it, and how many folders up do I need to go?

Which is annoying, but at least it is a real question with a real answer.

The failed clever fix

There is a more Eleventy-ish way to solve this using pathPrefix.

Since the site lives under /mcgowen/, it is tempting to tell Eleventy:

pathPrefix: "/mcgowen/"

Then use filters to generate the correct URLs.

That can be a good solution. It can also make things confusing very quickly if only some of the links are using the prefix correctly, or if local testing and hosted testing are not behaving the same way.

In my case, the cleaner fix was to keep the site simple and use relative paths.

Sometimes the clever solution is the right one.

Sometimes the clever solution is just a second problem wearing a tie.

The browser cache lied to me

At one point, the CSS looked broken even after the paths had been fixed.

This is where the browser entered the conversation and decided to make everything worse.

Browsers cache CSS files so pages load faster. That is usually good. But during development, it means the browser may keep showing an old broken version of the site even after the files are fixed.

The answer was a hard refresh:

Ctrl + F5

Or in Chrome DevTools:

Right-click refresh → Empty Cache and Hard Reload

This is one of those things everyone “knows,” and yet it still manages to waste time.

The lesson is simple: before assuming the whole build is broken, make sure the browser is not confidently showing you yesterday’s mistake.

The homepage article problem

Originally, the homepage article section used images and thumbnails.

That looked nice for a few posts. It also created a maintenance problem.

Every new article would need:

  • a thumbnail
  • the right dimensions
  • the right file name
  • a matching link
  • a card layout that did not look weird next to the others

That is fine if the site is mostly a gallery. It is less fine if the point is writing.

So the better approach was to make the homepage show a simple recent writing list.

No thumbnails. No image hunting. No cropping. No “do I really need a picture for a post about permalinks?” crisis.

The homepage can just loop over the newest articles:


  <article>
    <h3>
      <a href="articles/i-just-wanted-a-better-funnel-report/">I Just Wanted a Better Funnel Report</a>
    </h3>
    <p></p>
  </article>

  <article>
    <h3>
      <a href="articles/data-work-is-translation-work/">Data Work Is Translation Work</a>
    </h3>
    <p>An essay on why data work is often less about numbers and more about translating between human questions, database structures, definitions, and decisions.</p>
  </article>

  <article>
    <h3>
      <a href="articles/building-this-site-eleventy/">Building This Site Part 1</a>
    </h3>
    <p>A short write-up on turning a static Bootstrap portfolio into a Markdown-powered Eleventy site with articles, series, images, and a proper writing archive.</p>
  </article>

That makes the homepage self-updating.

Add a new Markdown file, rebuild the site, and the newest article appears.

This is the kind of laziness that turns into good design.

The search.html problem

Eleventy likes clean URLs.

That means a file like this:

search.html

may get built into this:

_site/search/index.html

Then the URL becomes:

/mcgowen/search/

That is fine for most normal website use. It is not fine when a class assignment expects a literal URL like:

/mcgowen/search.html

The fix is a permalink at the top of the file:

---
permalink: search.html
---

<!DOCTYPE html>
<html lang="en">

That tells Eleventy exactly what output path to use.

So instead of trying to be helpful and making a folder, Eleventy leaves the file as:

_site/search.html

Sometimes you want clean URLs.

Sometimes the assignment says search.html, and the assignment wins.

The article page got less bloggy

Another small change was moving tags out of the top of the article.

At first, the tags were near the title. That worked, but it made the page feel more like a generic blog template than an essay.

So the top of the article became simpler:

Title
Subtitle
Author
Date
Reading time

The topics moved to the bottom.

That feels more natural. You read the article first, then see what it connects to. It also keeps the opening from looking cluttered.

Small layout changes like this are easy to dismiss, but they matter. The page should tell people what kind of thing they are reading before it starts throwing metadata at them.

The homepage voice changed too

Once the articles had a more personal tone, the homepage started to feel a little too polished in the wrong way.

The old version said something like:

I turn operational data into clear reports, practical tools, and better decisions.

That is not terrible. It is also the sort of sentence that could appear on several thousand consulting websites.

So the homepage language got a little closer to how I actually write:

I build reports, tools, and systems that help turn messy operational data into something people can actually understand and use.

That feels more specific. It also admits the basic truth of the work: operational data is usually messy, and “understanding what the number means” is often the real project.

What changed after Part 1?

The first round made the site work as a writing system.

This round made it work more reliably as an actual hosted website.

The main additions were:

  • relative paths that work under /mcgowen/
  • article links that do not assume domain-root hosting
  • image paths that survive being two folders deep
  • a homepage recent writing list
  • fewer thumbnail chores
  • .html permalinks for school assignment pages
  • less cluttered article headers
  • better homepage copy
  • remembering that browser cache exists, unfortunately

None of this is especially glamorous.

But this is most of what building a site actually is: fixing small assumptions until the thing behaves in the real place where it has to live.

Final thought

The first version of a project usually proves that the idea can work.

The next version proves that you understood all the annoying details you skipped the first time.

This site is somewhere in that second stage now. It is not complicated, but it has a structure. It can hold articles. It can grow. It can survive being hosted in a subfolder, which is apparently a meaningful achievement.

And, most importantly, I no longer have to find a thumbnail every time I want to write something.

μέτρον ἄριστον
“Measure is best.”
— Greek maxim