Apr 1, 2022

Astro

One of my reasons for having a personal website is to have a place to experiment with technology. I’ve been using VuePress for a while even though it’s more of a documentation tool than a personal blogging tool. Last year I upgraded VuePress from v1 to v2, and this year I had my eye on VitePress. I began the migration but then the Astro project caught my attention. As you can see from this post, I’ve moved my personal site over from VuePress to Astro.

I think that VuePress and VitePress are probably not the the right tools for what I’m specifically trying to do. If the goal is simply to put some markdown files on the web, then just about any SSG is fine. Astro is a little bit closer to Nuxt or SvelteKit though, and I appreciate what they’re trying to do.

Here are a few things I learned migrating from VuePress to Astro and Tailwind:

• You can embed components in Astro’s markdown, you just have to import the component in the frontmatter.
• Instead of wrapping non-SSR components with <ClientOnly> tags, Astro uses a directive. It would look something like this: <YourComponent client:only />
• Both Astro and VuePress choose some markdown extensions, but VP gives more out of the box. For example, to enable emoji shortcodes (:+1: = 👍) I had to install and configure remark-gemoji.
• Local search is not not included like it is with VP. I don’t miss it, but it could be a dealbreaker for some.
• There doesn’t seem to be an easy way to restore VuePress’s custom containers. Maybe I overused them.
• If you used a lot of inline code and now you’re using Tailwind typography, you have to override the part where it helpfully adds graves back in. Otherwise all of your inline code will look `like this`.
• I got caught on a known issue (#2146) about embedding fonts from npm packages, but there’s a workaround.

Here’s the astro.config.mjs that worked for me (see update for more recent version):

import { defineConfig } from "astro/config";
import vue from "@astrojs/vue";

export default defineConfig({
  buildOptions: {
    site: "https://barnabas.me",
  },
  integrations: [vue()],
  markdownOptions: {
    render: [
      "@astrojs/markdown-remark",
      {
        remarkPlugins: ["remark-gfm", "remark-smartypants", "remark-gemoji"],
        rehypePlugins: ["rehype-slug"],
      },
    ],
  },
});

Switching platforms is kind of like moving house. It forces you to take stock of what you have and clear out junk you don’t really need. If it’s still in the box 📦 since the last time you moved, maybe it’s time to throw it out. 🗑️