mariociavarella.it: Building a Portfolio from Scratch

Why Build It Myself

I didn’t want a template. Templates look fine, but they all feel the same and you spend more time fighting the theme than adding content. Building from scratch meant I could shape every detail to fit what I actually needed: a place to show projects, write technical articles and let people get in touch.

The site runs on Astro, mostly static with server-side rendering where it makes sense — forms, comments, view counters. Everything else is pre-rendered and served from the edge. It’s fast, cheap to host and easy to update. That simplicity extends to the design decisions too.

Design and Interaction

The visual style comes from a set of CSS custom properties that control colors, spacing and typography across the entire site. Dark mode works out of the box by swapping color values while keeping everything else the same. Fonts are Inter for body text and Space Grotesk for headings — both readable at small sizes and fitting the slightly technical aesthetic I was going for. Animations are minimal: subtle hovers, smooth transitions, nothing that gets in the way. There’s also an idle screensaver that kicks in when the tab is inactive — it started as an experiment and I kept it because it looks nice and reduces CPU usage when no one’s looking.

For engagement, I wanted likes, comments and view tracking without forcing anyone to log in. The solution is a simple fingerprint based on request headers — enough to prevent spam, not enough to identify anyone. Views get counted on page load, likes go through a rate-limit check, and comments pass through basic sanitization before storage. Nothing fancy, just enough to keep things usable without building a full auth system. All of this is backed by a small MySQL database on the shared infrastructure.

Architecture

The codebase follows Astro’s conventions with minimal abstraction:

• /src/content/ — Markdown files with typed frontmatter for articles and project notes.
• /src/lib/ — Utility functions for database, validation and external APIs.
• /src/pages/api/ — Serverless endpoints for likes, comments, views and the contact form.
• /src/components/ — Astro components with minimal client-side JS.

Most pages are static HTML served from the edge; SSR only kicks in for pages that depend on live data. A small admin panel handles comment moderation without external dependencies. This structure keeps the site fast while giving me full control over every moving part.

What I Got Out of It

Building the site taught me a few things worth remembering. Owning the stack makes debugging easier — when something breaks, I know exactly where to look. Static-first still makes sense for most use cases; SSR is powerful, but most pages don’t need it. And design systems aren’t just for big projects — even a personal site benefits from consistent tokens and reusable components.

The site keeps evolving as I add new projects and articles. The foundation is solid enough that content is now the easy part.

This project note was last updated on December 28, 2025 and refers to project version v0.4.2.