Man on box

manonbox.io

Yet another portfolio website. This is a simple static site/blog deployed to Github pages, but I wanted to experiment a little and roll my own site generator.

Motivation

To build a static site generator with:

• A typed language
• Automatically update site with master branch
• Support HTML templating
• Support Markdown format
• Use as few dependencies as possible
• Easy to extend for blog purposes

I absolutely love Astro, it is my go to tool when building static sites. It has a bunch of amazing features and is highly optimised for web. I would say this is my favourite framework in the JS ecosystem. You can go so far using just Astro and if you need it, you can reach for a frontend library like React or Svelte if you need some fine grained client-side reactivity.

However, if you opt for Astro, you need to use Javascript (or Typescript if you want to keep your types) and all the caveats this brings, like the requirement to use many dependencies just to get started. At least with Astro, these dependencies are hidden from the user (you're not required to ship any JS to the client if just using Astro) - which is great! However, there are still a lot of dependencies to manage and maintain.

As an example, I have a small personal project which uses Astro, Typescript and Tailwind CSS. If I list all the dependencies of this project (npm ls -all), there are currently 1101 dependencies in total. A positive mention is that these are all dev dependencies, so they are not exposed to the client, but this is a tiny personal project and these dependencies will require maintenance as the project goes on.

As a result, most projects built with Frontend frameworks like React/Svelte/SolidJS and all the extra dependencies you'll be using (Vite, Webpack, UI component libraries, testing frameworks, etc etc), inherently make your project warm-blooded (they require constant maintenance, if you want to keep dependencies up to date or secure), as well common breaking changes as these libraries evolve and compete with each other.

This can be okay, but as soon as you are maintaining multiple projects, sometimes just keeping them up to date can generate a lot of TOIL.

Now there are many alternatives to JS frontend frameworks (such as Django, Laravel, Hugo). But what if I just want to build a simple static site to host a blog? How simple can I get? Do I need to use a library?

I love Go and want to continue learning in this space. So I wanted to see how far I could get by just using the standard library to build my own static site generator, and turns out, you can go pretty far.

The project is small, and self explanatory with just Tailwind and Tailwing Typography as a node dependencies (for transparency, the versions at writing contains 150 dev dependencies).

Development

Prerequisites

• Go 1.22
• NPM

Install dependencies

• Install Go dependencies

go mod download

• Install NPM dependencies

npm install

Start server

To serve the static site at http://localhost:3000:

make serve

To build the static site, ready to be deployed:

make build

For development, build the project and watch for changes with:

make dev

This re-compiles the project and reloads the page when making changes. Air is required to support this functionality.