It's alive!
Braaaains...
Okay, well I missed Halloween by one day. But nevertheless... it's living!
Today I migrated my blog from (GitHub-driven) Jekyll to instead use the blog capabilities of Roq, a static site generator driven by Quarkus. Overall the migration was pretty simple, but I'll go over the steps I took here anyway, in case anyone finds it helpful.
I had a few reasons for wanting to move, but mainly it's because I could never quite manage to build my site locally using Jekyll, which makes writing posts pretty painful. Ruby is just too finicky. I admire Ruby as a language - it's very cool - but I would prefer to have nothing to do with it in practice if I can avoid it.
Since Roq is backed by Quarkus, I can use its awesome development mode feature to check out the result of my edits as I go - in fact I'm doing it as I write this post.
Creating the initial project
I basically followed the steps in the Roq with Blogs post. All two of them.
First, create the initial project from your shell:
$ quarkus create app my-blog-name -x=io.quarkiverse.roq:quarkus-roq
Then, fire up dev mode:
$ cd my-blog-name
$ quarkus dev
Easy as that, the site is already up and running on localhost:8080.
Importing blog posts
Importing the posts was fairly easy. My Jekyll site used Markdown-formatted posts with front matter, and Roq also supports Markdown-formatted posts with front matter, so I just copied all the files from my old blog's _posts directory into content/posts and hit "reload" on the browser, and...
Kaboom! 💥
2024-11-01 12:04:51,193 ERROR [io.qua.dep.dev.IsolatedDevModeMain] (Aesh InputStream Reader) Failed to start quarkus: java.lang.RuntimeException: io.quarkus.builder.BuildException: Build failure: Build failed due to errors
[error]: Build step io.quarkiverse.roq.frontmatter.deployment.data.RoqFrontMatterDataProcessor#prepareData threw an exception: java.lang.IllegalStateException: Invalid layout: layouts/post in my-post-name.md
... blah blah blah ...
Turns out, the layout front matter value has a slightly different syntax than what I used with Jekyll. My old blog had:
---
layout: post
---
Whereas Roq prefers the layout argument to be more like this:
---
layout: :theme/post
---
In my opinion, the syntax should be a little flexible, particularly in the case (like my case) where I'm importing posts from Jekyll. So I filed a bug report. But I also fixed the entries to use the Roq syntax. (Update: it seems that the latter syntax is used when you're pulling from a theme, but the former syntax does work if you have your own custom layout. Good to know!)
I also ran into another problem where the page failed to render if there was no author: tag, so I added that as well, even though my blog has only one author (and just barely one, at that). Presumably, this is due to the default theme expecting an author tag. Regardless, I filed a bug for that one as well, because why not?
Now, we're up and running!
Intercepting old page URLs
My blog isn't much, but it has been around for quite a while; previously it was Jekyll, but before that it was a very crappy WordPress site. I wanted to make sure that those crusty old links still worked back when I imported them to Jekyll. And likewise, today (while I did want to take the opportunity to purge some of my less interesting, relevant, or simply more embarrassing utterances) I did retain a few posts that I thought had some small value. So I want to make sure that both the old WordPress links and the somewhat-less-old Jekyll links still work after this migration.
In Jekyll, you would use the redirect_from front matter item with a list of URLs, which causes those URLs to redirect to the current page versions. The Roq equivalent is to add the quarkus-roq-plugin-aliases extension to your pom.xml. This extension adds support for an aliases item which works pretty much exactly like Jekyll's redirect_from:
---
layout: :theme/post
title: Proper resource management
categories:
date: 2008-07-28 21:22:00
aliases:
- /2008/07/proper-resource-management.html
- /proper-resource-management/
author: dmlloyd
---
That's it! The old links immediately started working. This is almost too easy; I might get lazy. Well, lazier.
Overriding some defaults
I went through and updated a few of the defaults in the about.md, index.html, and data/*.yml files. I love the Roq logo, but it doesn't look like me. Well, it looks like me a little bit. But at any rate I prefer an actual photo, like one from when I was 15 years younger than I am now. Just look at that picture; it brings me back to a happier time, before I knew about such horrible things as COVID-19 and sciatic nerve pain.
Replace the old tree
OK, it's time to blast the old site and replace it with this shiny new one.
Step one is to commit this whole project into a new Git repository. I did it like this:
$ git init
$ echo 'target' >> .gitignore
$ echo '.idea' >> .gitignore
$ git add .
$ git commit -m 'Completely new site'
But... I already have a Git repository for the old site, and I don't really want to force-push the new site and lose my commit history. So, my strategy here will be to use git restore to create a single commit which wipes out the old stuff and replaces it with the new stuff.
$ cd ../old-site
$ git fetch ../new-site
remote: Enumerating objects: 45, done.
remote: Counting objects: 100% (45/45), done.
remote: Compressing objects: 100% (38/38), done.
remote: Total 45 (delta 7), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (45/45), 345.02 KiB | 9.86 MiB/s, done.
From ../new-site
$ git restore -s FETCH_HEAD .
$ git add .
$ git commit -m 'Replace with new blog'
Now, old-site has all the stuff that was in new-site, without any of the Jekyll stuff that was there before, but also retaining the full commit history. Nice trick eh?
Publish to GitHub Pages
Now the tricky part. Let's publish this thing!
Having a look at the Roq GitHub Pages configuration page, it looks like all I have to do is add a .github workflow, which should be fairly familiar to anyone who has dealt with GitHub Actions.
And... well, it didn't work. I get a 404 for my custom domain, and dmlloyd.github.io is not redirecting.
Save the CNAME
Well, when I cleverly smashed the old Jekyll site, I also deleted the CNAME file which GitHub adds for you. Re-adding the domain in settings fixed that (and automatically made a commit to my branch for me), so now the splash page appears for my custom domain as well. Great! Except not great. But, better!
Build from GitHub Actions
There's another switch that needs flipping in settings as well. Since I was deploying using Jekyll, I also needed to update my GitHub settings. Under "Build and deployment", there's a dropdown labelled "Source", where you can choose a branch or select "GitHub Actions". You have to choose the latter to get the site that is deployed using actions.
I had to update the workflow file with a couple changes as well: one, make sure that the checkout happens into path: blog, and two, make sure each Maven step executes in that path.
Now it all completes, and... here we are!