I migrated my site to Astro!

2024-12-29

If you’re reading this blog post, it means the new site based on Astro is now live!

Announcements

Here are all the breaking changes regarding my site that you should probably know about:

Motivation

I’ve gone through so many website frameworks that it’s honestly very hard to keep track. I used WordPress, Ghost, Jekyll and then finally settled on Hugo in 2021. For the last two frameworks, I used GitHub Pages for hosting, because I’m a student and it’s hard to beat the price of free.

When I settled on Hugo, I thought I’d stay on for the next couple of years. While the entire website worked okay, I was dissatisfied with a couple of things.

For starters, because I was (and still am) quite terrible at design, I decided to use a pre-made theme called anatole. While I am grateful that I was able to use it, the site built on top didn’t really feel like my own creation, even as I tried to style it my way.

Speaking of styling things, it was quite difficult to do with Hugo. Hugo was built on top of Google’s Go language, and it has its unique templating syntax. The idea of having to learn it to make even the smallest changes to my website put me off from actually customizing the look and feel of my website for a very long time.

But I liked the fact that I could just write for my blog by making a Markdown file, committing it, and pushing the changes to GitHub. Hugo, and the anatole theme I was using, had good support for internationalization (i18n), which I needed because I also translate my blog posts into Korean. This was so simple, in fact, that I was able to continue to post on my blog in the military back in 2021-23, by using my iPad to write Markdown in Working Copy and pushing it to GitHub.

However, the final limitation that had me fishing for alternatives was when I tried to add some JavaScript to my website. I had a bunch of utilities, and I’d gotten by with vanilla JS by just stuffing them inside <script> tags and forcing Hugo to render raw HTML inside my Markdown files (which was gated behind a config option that started with a scary unsafe keyword for no coherent reason). But as the scope of my tools and pages grew, I had to include more features and dependencies, and that meant using a JS bundler to compile my JS into the final form.

This was not a built-in feature for Hugo. I had to bolt on compiling JS with webpack, and while it sort of worked, it made the build process more convoluted. Worse yet, I couldn’t figure out how to neatly organize my source files and have webpack cleanly compile them into bundled files for Hugo to pick up. And the fact that I still had to learn the templating language if I wanted any changes made signalled to me that it was perhaps time to move on.

First try: NextJS!

I had some experience using NextJS for some of my personal and college projects, and thought it would be a perfect fit for my new website.

Unfortunately, I was about 40% complete with the migration when I realized that the built-in MDX compiler did not support relative imports for images. Nor did the next-mdx-remote repo support it. This was a problem, because I already had a huge collection of blog posts (67 of them, or 134 counting the Korean translations) written in Markdown, with images nestled in each folder for easy relative imports:

blog/
  2024/
    2024-12-29-i-migrated-my-site-to-astro/
      en.mdx
      ko.mdx
      imgA.png

For some context, this meant I couldn’t do something like this in en.mdx:

import imgA from './imgA.png';

I migrated my site to Astro:

<Image src={imgA}>

Instead, I would’ve had to move all of my images to the public/ directory, which was very messy and not something I was willing to put up with.

mdx-bundler looked like a potential solution, but it required having a separate bundler as a build step, and that reminded me too much of Hugo and the webpack situation.

At this point, the members of the Purdue Hackers Discord couldn’t recommend Astro enough, so I decided to try that next, even though I was really bummed that I couldn’t use something I was familiar with. But hey, maybe Astro is better?

(spoiler alert: yes it is, because you’re reading this blog post)

A rough start to the migration

I got started with the migration back in November 29th, so the entire process took exactly one month. But I swear that there is a good reason for why it took so long.

I had a couple of requirements for the migration:

Almost immediately, I hit a roadblock. Astro would refuse to render my previous RSS feed URL at https://ericswpark.com/blog/index.xml. I filed a bug report, but it sat dormant until this week. After some back and forth with Astro core maintainers, I figured out where the bug was coming from and submitted a pull request. Even though a member on the Astro Discord said they’d look into the pull request, as of writing this blog post it still hasn’t been merged, but it’s okay because patch-package is a thing and I can just remove the patch whenever they get around to merging it.

I decided that requirement #2 could be relaxed a little, and decided to move the URL from index.xml to rss.xml. It seemed more appropriate, and I could add more feed formats in the future, like rss.json.

After finals week passed, I continued work on the website migration. It took a while, because I had to write mostly everything from scratch. All the components had to be written for things like GitHub Gist embeds, the styling had to be written with CSS (although Tailwind CSS really helped here), and routing — especially i18n routing — had to be set up properly and to my liking.

But when you get past all of that?

The best of all worlds

The really neat thing about Astro is that mostly everything I can think of has first-class support. You want MDX? Astro has it. Want code syntax highlighting? Astro has it. Tailwind CSS? Astro has it. Want to add React? Sure. Vue on top? Why not. Server-side rendering? Config switch. Static site generation? The default. Their documentation is fantastic and their .astro files were just JS extended a bit with a frontmatter-like section, so I was accustomed to the framework in no time at all.

And because I could write the CSS from scratch, I had greater flexibility and freedom to customize the site however I wanted. (That being said, I’m still terrible at design. But I’m still proud of the homepage.) And Astro does some pretty nifty scoped styling, so that rules don’t conflict with each other. Global styles can still reach over and threaten to ruin your day, but you can just dial up the specificity to avoid that.

And despite that snag I hit in the very beginning of the migration, the rest of it went very smoothly, and I was able to hit all the requirements that I set out for myself!

Comparisons

If you’re curious, here are some of the before-and-after shots:

Homepage before (light mode)Homepage after (light mode)
Blog post example before (light mode)Blog post example after (light mode)

In particular, I’m very pleased about the following bits:

Of course, the site will always be a work-in-progress. But now that the big migration is over, I can finally get back to writing more blog posts that I’ve been putting in my to-do list.

That’s it!

I hope you enjoy the new site! If you have any suggestions or feedback, please reach out to be via email. In particular, please report any broken links, although I am pretty sure I’ve brought over all of them as I absolutely hate linkrot.

Also, I’ve taken the opportunity during this migration to hide a little Easter egg on the site. I personally think it’s cute. Feel free to let me know via email or Discord if you find it! (And no it’s not the blurb text in the footer.)