Moving TurnKeyLinux.org from Drupal to Hugo

TurnKeyLinux.org has accumulated a lot since the first Drupal version went online: appliance pages, documentation, release notes, screenshots, FAQs, blog posts, taxonomy terms and years of forum discussion. We are moving the public site to Hugo without pretending that history never happened.

The forum is being preserved as a read-only archive for now. New forum software will be a separate job. Old discussions still answer search queries and old links still arrive from package notes, bookmarks and other sites, so deleting them was never a serious option.

Why move

Drupal did several jobs for the site. Most of those jobs are now publishing jobs, not database transactions. Appliance descriptions and documentation change, but a visitor does not need PHP and MySQL to read them.

Hugo builds those pages ahead of time. Serving static files reduces the moving parts on the public path and makes the content easier to version, review and reproduce. It also gives us room to untangle navigation that grew around the old content model.

This is not “export HTML and declare victory.” A static copy can look correct while quietly breaking the ways people use it.

The URLs are part of the content

The migration keeps an inventory of Drupal routes, aliases and comment links. The build checks that each expected path has an output. It also crawls links in the generated site and checks fragments such as old comment anchors.

That catches failures a visual comparison misses. A page can be beautiful and still turn ten years of inbound links into 404s.

The archive also keeps old appliance pages reachable by direct URL. Appliances without a current TurnKey 18 release are marked deprecated and removed from normal discovery, search and related-app suggestions. Somebody following an old link gets an explanation. Somebody choosing a new server does not get steered toward obsolete software.

Structure before decoration

Drupal taxonomy contained useful relationships, but the old presentation often exposed them as long lists. The Hugo site turns those relationships into app categories, documentation subjects, FAQ topics, blog topics and screenshot collections.

Search follows the same editorial order. Current appliances come first, then maintained documentation, FAQs, blog posts, screenshots and archived forum material. The type is shown beside each result. A ten-year-old forum answer should not look more authoritative than the current manual merely because its title matched twice.

We are testing journeys as well as pages: discovering an appliance from the home page, checking its screenshots, finding its documentation, downloading an image and returning through a category. The same tests run at desktop and phone sizes. Keyboard use and visible focus are in the acceptance checks too.

What remains

The static site is still being tested and polished. The forum archive needs spam cleanup before it deserves a permanent home. After that we will connect it to the new discussion service without changing the archive URLs people already have.

The useful lesson so far is simple. A website migration is a compatibility project with a new design attached. Start with the routes and the ways people move between them. The home page can wait a little. A missing manual cannot.