A blog migration story

It's been a while coming, but over the last couple of months I've finally gone throught the process of migrating my blog content off WordPress and onto a statically hosted site. A few people have asked me why I'd go to the trouble of doing this, so while I'm having a festive break from proper Sitecore stuff, I thought I should write about my reasoning:

Why migrate? url copied!

This isn't the first time I've changed providers. Back in 2014 when I first started writing, I tried Blogger initially. That didn't last long though - I found formatting code samples to be such a pain there that it drove me to WordPress after a few months.

And WordPress has kept me mostly happy for the years since. But of late they've started moving my cheese quite a bit. They're in the midst of rolling out a series of enhancements towards a more modern editing UI. But in doing that they've made the workflow I've been using harder - and it's started to get on my nerves. Basically I don't get on with the new block editor.

So about a year ago I started looking into the idea of moving. I toyed with a few other more recent blogging platforms, but didn't find one I liked. So I started looking at hosting it myself, in order to have more control...

I tried a collection of JavaScript-based site generation tools like Gatsby, NextJS and Hexo. I quite liked Hexo, and got fairly far with creating a site based on that - but kept bumping into how my lack of JavaScript knowledge would cause issues for customising it.

So I went back to the drawing board and looked for something .Net based. And after a while I came across Statiq. It's an ongoing project to build a modern SSG using .Net core - and it fit my skills better.

So moving away from Wordpress gives me:

• Better performance
  Using an SSG is much better for lighthouse scores. Static files don't need runtime processing to render the content, so I can have pages that score very well:
• Control over the layout and style
  There have been a few occasions over the years where I've wanted to be able to mess about with the blog theme more than the freebie WordPress behaviour lets you. Not an issue if I build the HTML myself. Though I'm sure my designer friends would say this freedom is bad for other reasons... ;-)
• Picking my own domain
  Again, something I could have done with paid WordPress - but is easier with a static site, and ensures I keep ownership and control over everything.
• Reduced risk of the platform moving out from under me
  While Statiq might change in the future, it's open source, so I can always revert to a version which suits me. And while maybe one day I'll have to move hosting or DNS provider, neither of those are as big an issue as WordPress changing in ways I don't like.

So I spent some time on hacking up my own site theme, and pulled together a migration tool to transfer content. And then spent far too long fiddling with the details...

What is the tech stack? url copied!

As mentioned the SSG for the new site is Statiq. It's an open source project built on .Net Core. It takes a theme built on Razor Pages, and applies it to markdown files for all your pages and posts. Statiq is just a framework for running content creation pipelines, so you can compile it into whatever application you want.

It comes with pipelines which do all the common blog applications, and I found I didn't need to tweak very much of its out-of-the-box behaviour, outside of the razor files:

So I've got a .Net Core console app project (which happens to be running under .Net 6 - I was very pleased with how easy upgrading to that was) which generates all the mark-up, and handles the static files for the site. And I've made a couple of changes to the standard behaviour:

• I modified the default code-block formatting to use the Enlighter.js framework. That gives me pretty code blocks in a style that I like.
• I added a pipleline to generate OpenGraph images for each post, based on the example in this blog post. So social shares for any page get an image (along with other metadata) without any extra authoing effort.

Both of those were pretty easy changes to make thanks to the way Statiq works.

The theme then uses Tailwind CSS and Alpine.js. I've made a first pass at minimising Tailwind, but there's more to do there to get to "nice" styles.

The build process for Statiq isn't that fast with 260+ posts and all their images. But it works, and the output is easy to host. I'm pushing that to a GitHub pages site, with a bit of powershell to automate the build-and-commit task. While there are lots of different static file hosting solutions I could have used for this, that was just the simplest choice.

And finally, the DNS for the custom domain for the GitHub Pages site is handled by Cloudflare. Nothing clever there - just a CNAME entry in the DNS that points to the relevant thing in GitHub.

What's still to do? url copied!

Plenty. Other than a few more years of writing every couple of weeks, I've got a bit of a backlog of work still to do:

• There are a few migration tasks left. There are some big files left on WordPress that I don't want to host in GitHub Pages. So they need a new home. And eventually I'll need to exclude the old site from Google too.
• The styling is pretty hacky right now. While I've used the Tailwind CLI to minimise the default CSS file and got it fairly small, most of the UI still has lots of basic Tailwind classes applied. So eventually I'll need to work out how to put a better approach to styling in. Statiq does automatically compile sass into CSS - but I've not looked into how you can "include" other frameworks yet. So maybe I'll need to make use of a more traditional css build script. Similarly I'm pretty sure I could reduce the size of the JS being delivered with some more work.
• There's some particular situation which can cause the initial start-up of the Statiq build/preview engine to fail. Sometimes a bit of data in their pipeline state appears to go wrong and it gets a lot of null-value exceptions as it processes your templates. Restarting it, or clearing out the current output and cache seems to resolve the issue. But I don't know why yet, and I'd like to understand that and (hopefully) fix it. So there's a debugging task there.
• I'm not a fan of the current cookie banner code. Apart from not being convinced it's needed, it annoys me that it will still flash up briefly on page loads after it's been dismissed. I must be able to do better than that.
• And I need to find a better markdown file editor - I need to do a bit of research into customisable editors, where I have have snippet insertion, so I don't have to keep looking up the right order for brackets in markdown links...

But despite those things that need sorting, the initial migration seems to be a success. I wonder how long it'll take me to finish all those remaining migration tasks?

↑ Back to top