HomeBlogResume

Building an Astro site from scratch

4/9/2025

Building my personal website

I have wanted to get this site off the ground for a long time. It has gone through a number of iterations. From a Next.Js site, to SvelteKit, to raw HTML, and finally to Astro. Overall I’m really happy with it, but there are a few caveats. Check them out below or skip to the bottom

  • Skip the template

    Unless you are building a much larger site from the get-go, I would recommend skipping the template, unless you can find a particularly barebones one. I had assumed that it was a good idea to start with one, but then there is a ton of stuff to remove. A million images, sections, etc. I wanted something simple, but the template was just not the way to get there. I blew everything away and spent a few hours here and there for a week or so to just start from scratch.

  • Start with static

    Astro starts in this mode. Don’t get over your ski tips and start adding dynamic stuff right away. Keep it simple, get acquainted with the syntax, and then consider if you even need to go SSR. On the flipside, it’s very easy to add an adapter and start producing dynamic content if need be.

  • Don’t overcomponent

    .astro files are great. In fact, this fun little list element is an astro component, interactivity and all. But don’t go overboard. The majority of the content on this site is just markdown/MDX. It was easy to get wrapped up in the weeds initially coming from React.

  • Consider raw Javascript

    Don’t get me wrong, I think React, Svelte, and all their friends are fantastic and I am not a dogmatic “vanilla Javascript ONLY” kind of person. But, modern Javascript has come a long way, and for a lot of use cases, you most likely won’t even need a framework. If you want a littler interactivity, you can get a long way with just a little bit of vanilla js.

Almost a silver bullet.

For as much as Astro does, I have found myself a few times deep down a rabbit hole trying to fix something. Whether it’s code highlighting in MDX files, trying to get mermaid js working right, getting markdown plugins to run consistently, it’s not like Astro is this perfect solution. But I do want to highlight the things I think it does really well.

  • Simplicity

    Astro is simple. It has a mostly small API, and the documentation is (for the most part) fantastic. Some things I just couldn’t get working (astro:env/server being probably the most time consuming before just falling back to using process.env). If you don’t overcomplicate it, Astro won’t do it for you. Start with some markdown and some .astro files and it kind of just works. The static output really could not be simpler.

  • Progessively enhanceable

    I found Astro fantastic to start small and then grow incrementally with. Here’s the rough timeline of my site:

    • Started with just static .astro pages.
    • Moved content to md files with the content api.
    • Added some interactivity with .astro components and started to use some .mdx files.
    • Enabled SSR and adapted some of the pages to use features of it.

  • Lots of extensions that just work out of the box

    I have been really impressed with the number of plugins that just work. I have not had to do any crazy configuration to get mermaid, syntax highlighting, cloudflare, etc. to work.