Looks like I was just a week early at taking a first look at Astro! Astro 2.0 was just announced yesterday with some cool new features. In particular, it provides a type-safe way to interact with Markdown files. I decided to take this opportunity to migrate my website from Jekyll to Astro. Here’s how it went:

• Everything on my computer was suuuuper slow… Maybe it was just because I was running OBS + WSL on a fairly low-powered laptop. TypeScript would take over a minute to catch up with what I was typing, making intellisense all but useless.
• Also unrelated to Astro: my alt key kept sticking, making everything I pressed on the keyboard misbehave. That on top of my two finger scroll on the trackpad moving the caret left to right instead of scrolling horizontally drove me crazy. (I was able to resolve the scroll issue by the end of the night.)
• Okay, so Astro… was pretty good! Like my experience with Remix last week, I had to get over a couple bumps. To be honest, I think their docs could use a little work. To be fair, I tend to skim docs instead of reading from cover to cover, but there were certain things that would benefit from more explicitness.
  • When organizing content into subfolders, the slug generated by Astro contains the full path from the collection folder to the file. This is a reasonable behavior, but there is no way to change how that slug gets generated other than overwriting it in the frontmatter of each markdown file. If you want the subfolders to be part of the path, make sure you use a rest parameter in your page file ([...slug].astro). In my case, I just pulled the last bit off the slug when generating the pages and links.
  • I would love to be able to add derived data to the schema of the content. This would let me generate my own slug and place it right in the schema instead of having to recalculate it in multiple places. This could also be used to add categories based on the subfolders.
  • When generating the pages from the collection, the getStaticPaths function must return a list of objects with a property called params that contains a property that matches the dynamic route parameter. Each one of these objects will be accessible as Astro during rendering. So, if you have a file called [post].astro, getStaticPaths needs to look like [{ params: { post: <path> } }, ...]. I like the convention that Jack Herrington used:

  ---
  // src/pages/[post].astro
  import { getCollection } from 'astro:content';
  
  export async function getStaticPaths() {
    const blogEntries = await getCollection('blog');
    return blogEntries.map(entry => ({
      params: { post: entry.slug }, props: post,
    }));
  }
  
  const { data, render } = Astro.props;
  const { Content } = await render();
  ---
  <h1>{data.title}</h1>
  <Content />

  • I really struggled getting Tailwind working, but it was my own fault again. I installed it manually first and then found out that Astro had an official way of adding it. Because I already added it manually, Astro didn’t overwrite my tailwind.config.ts, which needed a specific setup to work with Astro.
  • After getting Tailwind working, I realized that I love using Tailwind for tweaks to a UI, but styling a webpage from nothing is a lot. I would love to have the design system approach of Tailwind with the ease of use of a classless CSS framework such as Pico.css.
  • I like how my content is organized now, and I was able to get rid of the dates in the names of the files that Jekyll required along with the _posts directories. To get rid of those dates, I learned how to use the rename tool in Ubuntu to make bulk changes.
  • Deploying the site to Github Pages was a breeze. It gave me a second wind that carried me to the finish line around 3am. Now that I have the full site migrated to Astro, I’m excited to tweak a bunch of things! I can rely on my existing knowledge of component driven design, instead of digging into the intricacies of Jekyll, as good of a tool as that was.

If you want to watch me struggle for an hour and a half, here is the livestream of the first part of the journey. I ended up working on it for another 5 hours after this.