Relative URLs are hard

Published Nov 8, 2020

I’ve been helping my brother build his UX Design portfolio as a website, and I’ve been learning a lot about what makes the Web difficult for newcomers. In this case, it was domain-absolute paths vs. file-relative paths.

The exact situation was two GitHub Pages sites where one was served at / and the other at /repo-name. For local development, both projects used <link href="/css/style.css" /> to refer to their project-specific CSS. But that breaks when pushed to GitHub because repo-name was loading the CSS from /!

The explanation is that the projects were served with different subdirectory strategies. GitHub Pages serves repos at URLs like, except for repos named which are served at This scenario included one of each, so only one project could safely use absolute paths. The other needed to either know its own deployed location to use absolute paths or only ever use relative paths. For someone learning Web development basics, this feels complicated and arbitrary. This would be even worse for someone learning computing basics in a time where ecosystems have intentionally hidden tree-like directory structures from end-users.

Anyway, our solution was to dump everything in the /-served repo and ignore the relative path problem forever!

While doing this, I also learned that I can’t describe this as well as MDN can. So read their explanation if this is still confusing to you. If it’s still confusing after that, don’t worry! No one’s making it difficult on purpose, but it does require a lot to build up to an explanation. Email me if you wanna talk about a problem you’re having!