I needed an escape while stressing about my (previously) upcoming wedding. Having some personal annoyances with how difficult it would be to personalize Docusaurus, I sat down and hacked at Astro for a day and a half. I came up with a fully working static website & blog in no time.

Requirements

I had just a few requirements for my site:

• The ability to write pages and blog posts with Markdown and MDX.
  • I originally used Docusaurus because I wanted to force myself to spend more time writing than tinkering with the page. This worked, to a point, and I’d like to keep it easy to focus on writing.
• The site should be served as statically built HTML pages.
  • There really should be no need for a big backend CMS. Just write pages and push to a source control origin.
• The layout should be fully customizable.
  • This is the kicker that is moving me away from Docusaurus. While much of the framework’s built-in components can be swizzled and replaced with custom versions, much of it still cannot, and I do not feel like I have the knowledge depth to contribute.

Options

I set out looking at options:

• Docusaurus I absolutely love Docusaurus. I will continue to use it for documentation sites as the first tool I reach for. But for my personal site, it just wasn’t cutting it.
• Next.js People seem to love this. I’m still not fully convinced that the weight of the development environment and the prescriptive way of building things is best for me. I have been forcing myself to use it for a couple things, but it just isn’t clicking as the killer framework to me.
• Gatsby No. Just no. Every time I see a Gatsby site, it pulls down at least 10MB of JavaScript. Honestly, I haven’t actually tried Gatsby in a number of years, but last I did, I was turned off by the ergonomics of it. I have no idea if the anecdote about JS size is real or just a red herring.
• Eleventy Looks great, haven’t tried it. (aside: The amount of effort the eleventy documentation spends trying to convince me to use it makes me extra skeptical)
• Astro I’ve heard a lot of rave reviews. So I started with this one, just thought I was diving in.

Accidentally choosing Astro

I started just toying with Astro for building my site, and before I knew it, within just a few hours, I was mostly done building the basic framework with something that was pleasing enough to look at and work with.

Sitting back for a minute on it, I decided to just run with it. So far, it has been a pleasure to work with and has actually inspired me to really get some content written. Let’s hope it continues.

Details

Framework: Astro

As stated above, I sort of accidentally ended up going to production with Astro. I really liked how easy the plugin system is and the things the community has build:

• @astrojs/mdx
  • While I want to write with Markdown, it’s really hard to make things beautiful without some carefully crafted, reusable components. Being able to import and use them directly in Markdown is mostly a necessity now.
• @astrojs/solid
  • See Interaction: Solid-js for details.
• @astrojs/tailwind
  • See CSS: Tailwind CSS for details.
• @astrojs/image
  • I first started out manually creating multiple variants of images with webp, avif, png, and jpeg and writing the HTML by hand. That was a mistake. This plugin does it for you.
  • It definitely increases build times, but they’re still tolerable at this time. I’d love to see if this plugin could get a mode to pre-build the image variants and add them to source control.

Interaction: Solid-js

I originally thought that I wouldn’t need any interactive components, so I wasn’t going to add any React/Preact/Solid-js/etc framework.

But then I realized that I’d like a dark-mode theme switcher with the ability to use both automatic selection as well as user-defined preference.

I’ve used Solid-js for some small things before, and the small weight of the library seemed like a good choice for now. I’d like to do a comparison using Svelte, Vue, Lit, and bare web components. That’s going to be for another day, though.

CSS: Tailwind CSS

I’ve been here since CSS was first introduced. Heck, I was here using nested <table> and <imagemap> elements. CSS is great, but if there’s one thing that has really changed the way that I write CSS since CSS-in-JS, it’s Tailwind CSS.

Mostly, it’s easy, it’s predictable, and I don’t really have to think too hard to create something beautiful. Especially paired with the typography plugin – making a plain markdown post easy to read has never been more simple.

Hosting

I was originally hosting my site on Github pages, until I realized that the longest cache time set for any resource is 10 minutes. I quickly changed over to Netlify today without much fuss.

I really can’t complain after measuring using various tools and having the home page come out super fast, performant, accessible, and search optimized.

View source

Go and take a look! I have kept the code for this site open source and MIT-licensed (except for blog posts, images, and page content).