aka “Dr Jekyll and Mr Blog”
This blog has moved around enough that “new” probably needs an asterisk.
Some of these posts began life in WordPress. Later ones passed through Ghost, and still others arrived wearing Medium’s particular flavor of formatting. Each platform made publishing easy in its own way: open an editor, move some blocks around, click a button, and trust the machinery behind the curtain.
Now I’m trying something different: GitHub Pages and the open-source Jekyll project.
The repository is the CMS
The publishing process looks less like operating a traditional blog and more like maintaining a very small software project:
- Write a post in Markdown.
- Add a little YAML front matter for the title, date, tags, and layout.
- Commit it to a GitHub repository.
- Let GitHub Pages run Jekyll and generate the static site.
There is no production database full of posts and no server-side publishing application waiting for someone to remember its password. The content, templates, configuration, images, and revision history all live together in the repository.
Calling this a headless CMS is probably stretching the term. There is no content API or separate editorial service here. It is closer to a headless-ish, Git-backed publishing system: Markdown is the content store, Git is the history, Jekyll is the renderer, and GitHub Pages is the host.
The repository has effectively become the CMS.
Migration as digital archaeology
Converting the old posts has been the interesting part.
WordPress exports, Ghost exports, and Medium-flavored HTML may all describe roughly the same things—titles, dates, paragraphs, links, images—but they do not describe them in quite the same way. The basic conversion is only the beginning. Then comes the archaeology:
- preserving original publication dates;
- rebuilding front matter;
- repairing image paths;
- translating embeds and shortcodes;
- keeping old URLs working where possible;
- removing bits of platform-specific markup; and
- deciding whether an ancient broken link is history or just clutter.
Markdown gives all of that material a reasonably neutral home. It is plain text, readable without the original platform, and portable if I decide to move everything again. Given the history of this blog, that last part feels less hypothetical than it probably should.
Why trade the GUI for Git?
I have spent plenty of time tinkering with GUI-driven blogging platforms. There is something pleasant about logging in and seeing a polished editor waiting for you. There is also something strange about having years of writing locked inside an application, database, export format, or business model that may change underneath it.
This setup makes a different trade:
- I get version history, diffs, and backups through Git.
- I can edit with whatever text editor I want.
- The published site is made of simple static files.
- There is less server and plugin maintenance.
- The content is not inseparable from the publishing platform.
In exchange, publishing now assumes some comfort with Markdown, Git, configuration files, and the occasional Ruby-shaped rabbit hole. That is not necessarily simpler for everyone. For me, at least right now, it is a more interesting kind of complexity.
Full circle, with better plumbing
Moving away from a graphical CMS feels a little like going backward: files in folders, text in an editor, and a build step between writing and publishing.
But it also feels like coming full circle with better plumbing.
The old workflow was “write in a website that manages the website.” The new workflow is “write a file, preserve it in version control, and generate the website from it.” The public result is still just a blog. Behind it, though, the content is becoming a collection of durable files instead of cargo packed for whichever platform happens to be carrying it this year.
We will see whether this makes me write more often.
At minimum, it has already given me something new-ish to tinker with.
Down the rabbit hole
A few useful accounts from people who took similar routes:
- Moving from WordPress to Jekyll — Tobias Ahlin, 2013. Includes thoughts on preserving old URLs when moving more than 100 posts.
- Migrating from Ghost to Jekyll and GitHub Pages — a migration motivated partly by reducing infrastructure and maintenance.
- Migrating Blog to Jekyll — a useful example of gathering content from multiple earlier platforms, including Medium.
- Migrating From WordPress to Jekyll on GitHub Pages — a March 2022 walkthrough covering export problems, URLs, images, and GitHub Pages.
- Add a Headless CMS to Jekyll — an example of the more literal headless-CMS model, where Jekyll consumes content from an external API.
Follow @mike11stevens
