Big Site Update!

Finally, the future is here

With the publishing of this post (which hopefully goes smoothly), my site will be running on Nuxt 3, and be built with the Content plugin. This post will detail the challenges I encountered during the upgrade and how I went about solving them.

If you aren't familiar with how my site was built before, I detailed some of that in my first post here. Essentially it was built in between major versions of Nuxt, and I used markdown-loader for webpack with the hope of switching to Content in the future. It seems it paid off, as Content is still around and better than ever.

The Basics

Nuxt 3 gives you a lot for free that I had manually set up before, such as sass support.

Sass had its own breaking changes, mainly around the use of import and mixins. I was able to set up globally available variables and mixin blocks, but now I need to prefix every reference to them with <partial name>.. For example, in my old setup I used $size-large but in the new setup I have to use sizes.$large.

There were a few other small changes, including tighter integration with TypeScript (which I am not practiced at), but for the most part I was able to create a basic Nuxt app and then drop all my old components, assets, and pages into the new version and it kinda worked.

Some things are definitely nicer are more streamlined with the new setup, but the biggest changes came from switching from using markdown-loader to using Content.

Content - Benefits and Challenges

The biggest difference between how I used to manage post metadata and how it's done with Content is the use of Markdown Content files, which are prefixed with yaml metadata. This is one of the areas I find the documentation fairly sparse, and would like to see expanded more, but with a bit of tinkering I figured out how to add data of different types and then query them.

Instead of having a single content.js file where I manually maintain a big javascript object with all the blog metadata, Content reads all my markdown files and populates an sqlite database. I think I would have had a better time working with this had I set up proper javascript debugging, but I haven't set up debugging for Node or Nuxt in a while and didn't feel like thinking about it. Using console.log to figure out the whole query api with Content was annoying, and the docs for Content don't cover data transformations very well in my opinion.

Still, it's pretty powerful and I was able to make all of my static defined metadata into dynamic queried data, which is really cool and will make updating my website a lot easier in the future!

RSS Feed and Build-Time Generation

This was the trickiest part to figure out. I couldn't find much information about accessing queryCollection from the build context of site generation. After trying a bunch of stuff, I eventually settled on a Vite build hook which directly queries the internal sqlite database rather than trying to use Content's abstracted query layer. I'm sure this will be a bit more fragile in the long run, and I should probably add some more validations and checks in that step that can recover from unexpected schema changes. I guess this could probably be solved by having some sort of unit testing. Go figure.

After the RSS gets generated, I also generate meta.json to store the build date of the website. This seemed like a good enough place to generate it since I'm already writing files there.

Next Steps

Now that the big stuff is done, there's a few issues I want to tackle still. The accessibility of my website isn't fantastic as far as I can tell. I think I can do a lot to improve it. Also, there's differences between different browsers for how the site looks, which isn't ideal. Header links are rendering kinda weird, and I'd like to improve that.

I probably want to do some other formatting stuff and maybe add a sitemap.

That all can come later though, for now I am ready to push the button and hope this update goes live without a hitch. I'm not sure that it necessarily will since I'm also upgrading my gitlab-ci stuff to use a newer version of Node, but we'll see.

Onward!