Architecture of this blog

A quick overview of the main components and decisions behind this blog.

Table of Contents

Requirements

Functional

• It is a Blog
  • Shows a list of posts
  • Can present a single post
• Easy to add posts
• Easy to edit posts
• Supports basic text formatting
• Supports code highlighting
• Optional - Allow visitor feedback
• Optional - Count impressions

Non-Functional¹

• Cheap to host
• Fast to load
• Low runtime cost
• Low complexity
• Tech mostly under my control (i.e. no blogging services)

Solution

Given my familiarity with git and markdown: perfect blog would be a repository of markdown files. Very easy to edit and to track changes. Except the visitors might find it cumbersome.

Static Site Generators (SSGs) solve this problem. As the name says they generate a static website, usually with markdown or something similar as an input.

Jekyll is a SSG i’ve found to be popular when toying with this idea. It seems very pure and minimal - kind of perfect. However it won’t trivially support adding complex functionality (like feedback). And i want to keep that door open. I found that Astro is a web framework that does SSG, but can allow extending the site massively. Its modern, widely used, and ticks all the boxes. That’ll be the choice!

Hosting

GitHub Pages was the first idea. However i have it tied to some older experiment already. Cloudflare and Netlify provide similar service. I chose to go with the latter for no particular reason, maybe because big chunk of traffic goes thru Cloudflare already, who knows. They all offer free tiers.

Netlify was scarily easy to set up. Provided you have pushed your repository with a valid Astro project to GitHub. You can just grant Netlify app the permission to access that repository. It likely set up some hooks to react on pushes.

Thats it, when a new git push comes in, Netlify builds the project to update the website. All done in ~30 seconds.

Domain name

In this state the address for the blog would be something-like-7h15.netlify.app. Of course i want my own domain name, i already paid for it at namecheap. This too was very easy. In the admin panel for the domain at namecheap, I just needed to point to Netlify nameservers. After that Netlify can handle all the rest: correct DNS records, even acquiring a SSL certificate. Didn’t need to do anything else myself.

The Astro experience

Now the groundwork is done, its time to prepare the blog itself. My goal is to deliver the blog, and not to go into details of web design or development. Thus i chose AstroPaper theme as a starting point. It appears to be minimal (UI wise), thus timeless, but capable theme.

My only nit regarding Astro is that the content files are not as decoupled as i envisioned at the start. They are stored in the same repo where the rest of the site is. Secondly these blogpost files require a metadata header (called frontmatter in Astro) that is specific to this theme, such as:

---
pubDatetime: 2025-04-5T12:00:00Z
modDatetime: 2025-04-5T12:00:00Z
title: Architecture of this blog
featured: false
draft: false
tags:
  - architecture
description:
  A quick overview of the main components and decisions behind this blog
---
// normal markdown content follows

Fair enough, this metadata needs to live somewhere. For repository separation there exist solutions. All of this means replacing themes or changing framework is harder. But given the volume of content i have, it’s fine.

Development itself is simple and enjoyable. Given I’ve enabled auto save in my editor, and the Astro dev server running in the container² reacts to filesystem changes: the dev preview updates automatically.

Publishing is also a joy, just push the main branch to GitHub and Netlify will take care of the rest. All of this allows very fast iteration, blockers are no more!

Tracking

Netlify does offer analytics, but it’s a paid feature. Another option would be hosting some open source tracker, but that would put me out of free tier as well. When looking at complete solutions: GoatCounter seems like a privacy-friendly, free alternative. I can add their little script to my root layout, and they will handle all the rest. Good enough!