/ 2 min read
How vist.al is built (no framework)
Plain HTML, CSS and JavaScript, a small Python build script, clean URLs, and page changes that never reload the music.
Maciej Dąbrowski · Vistal
This site has no framework. No React, no Next, no npm install. It's plain HTML, CSS and JavaScript, plus one small Python script that puts the pages together. Here's how it fits, and why I did it this way.
Why no framework
A portfolio is mostly text, a few images and some motion. A framework would add a build pipeline, a pile of dependencies and a JavaScript bundle that has to load before anything shows up. Without one, the page is readable the moment the HTML arrives, and there's nothing to update or break in a year.
One layout, many pages
Every page shares the same head, nav, footer and music player. Copying those into each file would mean fixing everything five times, so a short Python script does it instead:
layout.htmlis the shell, with a{{content}}hole in the middle- each page is its own file with a few settings at the top (title, description)
- each project is one file: the card on the work page and its own case study page
- blog posts like this one are Markdown files
Running python src/build.py writes out the finished pages, the sitemap and the RSS feed. Hosting is then just a folder of static files.
Clean URLs
Pages live at addresses like /work/jailmine, not /work/jailmine.html and not /work/jailmine/. The build writes work/jailmine.html and the host serves it without the extension. Locally, a tiny Python server copies that behaviour, so what I see on my machine matches the live site.
Changing pages without reloading
Clicking a link normally throws the whole page away and loads a new one, which would cut off the music player every time. Instead, main.js catches internal links, fetches the next page, and swaps only the <main> part. The address bar, the back button and the page title all still work as normal.
Two details make it feel instant:
- Pages are fetched when you hover a link, so by the time you click, the next page is usually already there.
- If anything goes wrong, it falls back to a normal page load, so nothing can get stuck.
What I'd do the same next time
Keep it boring underneath. The fun parts (the gate, the console, the radio) sit on top of plain pages that work without them. That's the same approach I take with client sites: the clever bits are extras, never the thing holding the page up.