A guide on how I built this website with Astro.
Motivation / Background
Recently, I decided to recreate my website (cade.site) from scratch. I had been using Jekyll for a while, but got annoyed with some of the quirks and lack of extensibility. I also wanted to use fancier component-based UI development (since I’ve been writing a lot of React lately). Upon researching on the web, I found Astro, that supports static site generation. I really liked that it supported basically every feature I needed:
- Markdown for content, embeddable in HTML
- They also support MDX for advanced markdown
- React for UI components
- Sass/SCSS for styling (although, CSS is all I really need)
- TypeScript for type checking (seriously,
- Able to be hosted with GitHub pages (or any other static site host)
- Additionally, GitHub actions are supported
- Supports image optimization and other plugins/integrations
Also, the DX has been amazing so far, so part of writing this post is to give a shoutout to the Astro team for making such a great tool. I highly recommend it to anyone who wants to build a static website. I haven’t used it for dynamic websites, but it does support Server Side Rendering (SSR) that looks really slick.
So, let’s get into it!
The code for this website is all located at github.com/cadebrown/cade.site.
I got started with a a minimal Astro project, and locally inspected a few templates I found online:
- Astro official themes
- bearblog: minimalist blog template
I ended up coming up with my own structure from scratch, but these gave me a good starting point. I’d recommend just cloning one of these and modifying it to your liking (or you can take mine!).
I am extremely opinionated on how software should look and behave. I’m writing for a specific audience, so I make a few decisions that probably don’t apply if you’re going for mass appeal. For example:
- I like
monospacefonts for everything (code, text, etc.)
- I like dark mode (I will support multiple themes, though)
- I like minimalism, in form and function
Basically, I just want a motherfucking website.
Overall, the structure of an Astro project is fairly simple:
astro.config.mjs: configuration file for Astro
public/: static assets (images, audio, etc.) for the website
src/: source files (Astro, JS, CSS, etc.)
src/pages/: the pages that will be the routes of the website
src/content/: contains just the content, in markdown
src/layouts/: contains all the reusable layouts
src/components/: contains all the reusable components
What I like about Astro as opposed to Jekyll is that it’s not so opinionated about being structured around a single “posts” collection. For example, Jekyll requires that all your content be in the
_posts/ directory, and that you use a specific naming scheme for your posts.
With Astro, if we have
content/blog/*.md that we want to map to
site.com/blog/*, but also
content/projects/*.md that we want to map to
site.com/projects/*, then Astro makes it easy to define different routes.
Developer Experience (DX)
As far as DX, Astro is amazing. The basic workflow to setup the project on a new computer is:
- Ensure you have requirements installed (NodeJS, npm)
- Download the repository
git clone https://github.com/cadebrown/cade.site.git
- Install project dependencies
- Run the development web server
npm run dev
I’ve only used Ubuntu so far, but Astro should be cross-platform. So far, my experience with VSCode has also been flawless, the suggested extensions make development fast with auto-completion, type-checking, and more.
GitHub Actions for Deployment
TODO: write this section
Now, if you’re still reading, let’s get into the nitty-gritty of how I built this website, UI-wise.