quarkus.io left Jekyll for Roq; its tests now run 42% faster
Victoria Shinder3 min readQuarkus has moved quarkus.io from Jekyll to Roq, its own static site generator built on Quarkus, and the change is announced by Holly Cummins on 21 September. For a reader the only visible difference is in the footer. For anyone who has ever put off a migration, the interesting part is how it was done.
The reasons for leaving are prosaic. The old site was Ruby, a language nobody on the team particularly wanted to write; some contributors could only build it inside a container and some could not build it at all; and the customisations people wanted stayed unwritten because of it. The reasons for waiting were size: roughly 4,700 pages in a mix of HTML, Markdown and AsciiDoc, four translated languages, custom AsciiDoc extensions and Jekyll plugins behind the guides, and a dynamic search bolted into the static output.
The migration method is the transferable bit. The team explicitly rejected pointing a model at the repository and letting it convert everything in one pass — too many edge cases, and the site changes every day, so nothing could be frozen. They also rejected a long-running fork mirroring incoming changes. What they built instead was a set of reproducible conversion scripts, in this order: wrap the old site in tests first, because there were none and 4,700 pages cannot be checked by hand; add Lighthouse tests to catch performance regressions; use models to build and refine the scripts until the tests pass; write a Roq replacement for the Jekyll localisation tooling, which had no equivalent (asciidoc-jruby-l10n); then merge.
Two consequences of that choice are worth noting, because they are exactly what a one-shot conversion would not have given. The same scripts were run against contributors' open pull requests, so nobody was handed a 40,000-file rebase and nobody lost work. And the scripts survive as a reusable converter, published as roq-it-jekyll, described as still being refined and not yet fully documented.
After the cut-over some things were missed — the post's own words are "post-merge panic" — and the regressions were fixed within a few days. The converter came to about 10,000 lines of new code.
What it means
Make a migration a script, not an event. The team's constraint was that they ship site changes daily and could not stop. A repeatable transformation means the cut-over date is a decision rather than a race, the same code rescues other people's branches, and the whole thing can be re-run after a review round without anyone re-doing the manual parts.
Tests first, on a codebase nobody wanted to touch. They had no tests because the site was in a language the team avoided — which is the same reason they wanted to leave. Writing tests against software you are about to delete feels like waste and is the only thing that makes the deletion checkable.
What the post claims, and what it does not. The one hard number on the outcome side is that the site's tests run 42% faster. Page load is described as "a little faster" and the Lighthouse improvement as "small but noticeable" — impressions, offered as such. Local authoring becoming a single ./mvnw quarkus:dev call is the change most contributors will actually feel.
Source: https://quarkus.io/blog/jekyll-to-roq/