dassen.dev - Building my first website with Astro

Why I wanted to build a website

I have been programming for quite a long time now, but most of the projects I worked on so far are never published. They are either private tools I built for myself or friends, or work done under freelance contracts. There are a few projects that either were or currently are public on GitHub, which is fine for other developers who want to look at the code. And while a GitHub README is alright to showcase a projects core functionality, it is not really made to document my work, the progress I've made and the challenges I've faced. I wanted a proper place to showcase my projects and explain them in detail, and maybe add screenshots and videos as well. Beyond showcasing my projects, I also wanted to use my website to create tutorials and guides based on what I have learned so that i can present my knowledge that I have gained from projects that I don't want to or can't share. Often when I solve a difficult problem or implement something interesting, I also just want to write about it. It was also the perfect moment to finally learn how to build a proper website. I've been honestly wanting to do that for quite some time now, but I never really got to it so far.

Why I chose Astro

When I first started planning this project, I wanted to keep it as vanilla as possible. I've already been working with JavaScript for a while now, and feel comfortable with it, but HTML and CSS are still pretty new to me. I didn't want to use five different frameworks with a ton of configuration files, dependencies, and giant boilerplate for my first proper website, and instead intended to just keep it light.

I discovered Preact when working on a fork of another project (more about that on the project page of Desolate Dungeons). What I loved about it was the component system. I could write reusable pieces of code instead of copying and pasting my header on every single page that I have. It made building my website much more enjoyable and easier to maintain. However as I kept working on this website I realized that I'm actually just building a content-focused website with maybe an interactive element here or there, and not a web application that needs state management and complex interactions. It also did not make a lot of sense to me to send so much JavaScript to the browser to just display mostly static content.

So I decided to switch over to Astro. I have heard about it before and before switching to it I read some more about it in the Astro Docs. It is a framework created for content-driven websites like mine, I could still use components, there was no unnecessary JavaScript overhead, and it has a great beginner tutorial (I felt like Preact's tutorial just introduced the different systems individually, whereas Astro's tutorial introduced the systems by guiding a user through creating a first blog). Looking back at it I think it was definitely a great decision for this project.

The building process

When talking about the building process I think I would skip right ahead to when I started with Astro, because that is more interesting than my learning phase with Preact.

The very first thing I started with was completing Astro's build a blog tutorial. It walks you through creating a simple blog from scratch, and teaches about how Astro projects are structured, how components and layouts work, and how to add interactivity to a website. In the end I had a working site, and I understood why things are set up the way they are.

Once I was finished, I felt ready to build my actual website from scratch. This was because the tutorial project got a bit messy and I wanted to structure my actual website a bit different, but I thought it was also a good idea to start anew to simply reinforce what I already learned. The Astro documentation was very helpful and I used it whenever I needed to figure out how to do something specific, like how to work with scoped and global styles, or how to work with content collections for my blog entries. The MDN Web Docs were also an amazing collection of different resources, which I used to learn how to structure HTML elements in my site and how different CSS properties behave. The great thing was that I already knew the little JavaScript I needed for some interactivity, so I could focus on learning how to structure and style my website with Astro.

I think if one wants to learn something, whether it is a new framework, or a new programming language, or something else, a tutorial or a guide can be very helpful at the beginning, but I find it really essential to create something without just following instructions. And if that is too difficult, one can always start with modifying something existing instead, my first few experiences with web development where also modifying already existing projects like the fork I talked about earlier.

Challenges I faced

My journey with Astro was not only smooth sailing. I wanted my blog entries to be in Markdoc format so I can use my components within Markdown content. That worked just fine, but when I was configuring my content collection for my blog entries about my projects, I had the idea that I could load entries dynamically from an API. This way I would not have to manually rebuild and redeploy my website everytime I upload a new blog entry. I created my own collector loading function, thinking I could just fetch an entry from an API endpoint and let Astro handle the rest. However I could not get it to render the Markdoc content at runtime. Thinking about it, it made sense that it didn't work, because at build time Astro has access to the configuration file and knows where custom components are, however both are missing in the distributable at runtime. In the end I decided to include all Markdoc content in my project and use a build-time collection, especially since all my content is relatively static and I would probably only upload or update something a few times a month.

What's next

I'm still thinking about how I can improve my blog workflow. A simple and fast solution would be using GitHub Actions to automate building and deploying my website to my server everytime I push a commit to main. I'm intending on adding that next. However I'm also reading about server side rendering with Astro and an experimental feature called "live content collections" to see if I can maybe still load entries dynamically somehow. While I don't really need it, it would be interesting to implement if I manage to get it working.

Something I also still want to do is move all my blog entries to the blog page instead of having a separate projects page for my blog entries about projects, and add a tagging system with a filter / search function to organize my entries better. I'm also thinking about replacing the projects navigation link with a dropdown menu for quick access.

Conclusion

Well I think that's it then. I will continue working on this site a bit and see where I can still improve it, but I think for now I'm mostly done. While this project was more focused on designing than coding compared to most of my other projects, it was quite fun and I do always love a creative aspect. And thanks for reading this post about my website!