I feel like no tech-adjacent writing would be complete without at least one post about how everything works. This one is no different.
I’m building this site for me, so I don’t need a lot of the features so-called ‘non-technical’ people would need. This includes a CMS system or support for multiple authors.
That being said, I don’t want to learn a lot of new tech to make this work. A lot of the choices I’ve made are around what I already know. These choices may not be right for you. My hope is to inspire, not to make a tutorial.
Let’s start with my requirements for a writing.
Requirements
These have evolved while making this site, but I’m listing them here to frame all the motivations for the tech used.
Requirements:
- Free to host
- No host lock-in
- Maintenance free
- Easy to add content
- Version control
- Scales
- Standard content format
- Can evolve with new technology
Equally important are the features I don’t really care about.
Non-requirements:
- A Point-and-click Content Management System (CMS)
- Social features, like cross posting to different sites
- Email lists
- Multiple authors or collaborative editing
- I don’t want to learn GraphQL for any reason
Options, options
Even with these requirements there are still so many options out there, including making my own content system. However, I wanted to avoid shaving the yak (too much) on this one, so I went through the options.
Some people will see the requirements above and scream “Static site generator!”. To that I say, “Why are you yelling at me?” and also, “That’s right”.
Even with that insight, there are still plenty of options out there, a whole website of options.
The main contenders are:
I ultimately went with Astro.
Why Astro?
While most static site generators check all my boxes, I think Astro is doing something special. Now at version 4, it’s not the new kid any more and a lot of the bugs have been worked out. The community around it is solid and growing, plus they tend to be more design focused. This makes for a wide selection of high-quality templates available.
Next.js is similar in that sense, but I’d be stuck using React. I’d rather take cold showers for the rest of my life than figure out how to use useEffect correctly 🥶. Astro allows me to mix and match frontend frameworks as they come in and out of fashion, but I’ll likely just use my new found love, Solid.js, for the interactive bits.
Hugo generates sites fast. However, it is full of Go-isms and I’m just not that interested in using Go more. It seems fine, but it’s not fun. I also don’t really care about build times because I’m building the site on someone else’s machine (erm, ‘The Cloud’). Additionally, the Hugo ecosystem is just a bit too nerdy for me. The templates available are made by and for technical people. They lack a lot of the design care that users of the modern web expect. The same goes for Zola, which is like Hugo, but written in Rust, so it’s Bettertm.
The other strong contender was Jekyll. I’ve used Jekyll before with some success. It’s the site generator that started it all and for that it will have a special place in my heart. I just can’t understand the language it’s written in: Ruby. There’s too much “magic” for me. Updates to Jekyll have also gotten fewer and fewer over the years. Take that as you will.
Astro in practice
So Astro it is. Although Astro’s documentation is 5⭐️ A+, it still has a learning curve.
First thing I had to do was find a suitable template. Here was the first hiccup. While Astro has a ton of great looking templates (Just Kagi “Astro Templates”), the reality wasn’t so easy. The Astro of today seems stable, but they have been through 4 major versions so far, each version being quite different from the last. This means many templates out there just don’t work anymore on the new hotness.
I’d find one I liked, to just get railroaded by all the changes I’d need to make to have it work. I finally settled on one made for version 2 and converted it to work with version 4. In hindsight I should have picked a different template, but the conversion experience helped me learn Astro pretty quickly. After about 4 hours I knew my way around quite well.
Here’s the configuration I ended up with:
export default defineConfig({
site: BASE_URL,
integrations: [
mdx(),
tailwind({
config: {
applyBaseStyles: false,
},
}),
solidJs(),
sitemap(),
playformCompress(),
],
});
I got MDX for converting Markdown (my preferred writing format) into HTML. Tailwind for styles. SolidJS for interactive parts. Simple enough for me.
Out of the box Astro provides some nice-to-have features like code highlighting, site map generation (SEO!), image optimization (webp is amazing, and now widely supported!), and “view transitions”. View transitions are something I didn’t know I wanted, but gives users the feel of a single page app without all the complexity. All with 2 lines of code and no ongoing maintenance. If you click around this site, you’ll get a nice fade between the main content without the common elements jumping around. ✨Fancy✨.
Otherwise, setting up Astro has been pretty smooth. It is a bit more opinionated than a lot of the other static site generators. The focus is on scaling content pages, with powerful utilities for managing metadata (Is this content a draft? What’s the publish date?). What’s nice though is most of this functionality is opt-in. You can bring in what you need, and not learn the stuff you don’t.
The simplest Astro site would be familiar to anyone who has made an HTML page before.
Going Live
At this point everything seemed good running locally on my laptop. But that isn’t very useful for a web site. It needs to run on the web.
While I can, and have, run web services used by millions of people using nothing but some Linux servers and quiver of Dockerfiles, I didn’t want to be “on call” for this site when things went sideways. I don’t want to get an email at 2am letting me know the site is down. All I want is to push updates to Github and go on with my day.
Thankfully, Astro can generate a pile of HTML/CSS/JS files that any number of hosting providers can serve up for basically free. I’ve used many of them, but I currently have most of my static sites on Netlify.
Sadly, I’ve grown suspicious of Netlify over the years as they seek to add services to monetize, but so far they have left my sites alone. Their free tier isn’t as generous as, say Cloudflare, but good enough for my use case. The main feature I like about Netlify is they can monitor a Github repo and run the build/deploy step when changes are pushed. I don’t need to fuss with Github Actions in order to tie different services together. It’s pretty set-and-forget. Perfect.
The whole build script amounts to:
npm ci && npm run build
I just push changes up to Github and about a minute later the site is live.
Wrap up
All the requirements have been met. The code is now all tucked in, nestled in their folders. You may be asking yourself, “Well, where is the code then?”. It’s not anywhere. Even though I release the majority of my code for the public, this is the one project I’m keeping for myself. Don’t worry, I feel a little bad, but I have my reasons:
- It’s a living codebase and it’s going to get sloppy.
- I’ll put draft writing in here that I may never want to release.
- I’m not innovating here, it will largely look like any other Astro site.
- I don’t want anyone else using it.
The major downside is not having an issue tracker in case when I break things. Y’all can still email though, right?