I moved the blog from microCMS to Markdown

When I changed the blog’s stack three and a half years ago I put microCMS in, and then I left it sitting there. While I was in the repo anyway, I moved article management into the repository itself.

The only thing that changed is where the content lives. The SSG is still Astro, and delivery is still Cloudflare Pages.

The main reason is that it’s easier to have Claude read the repo and write the post than to write it by hand.
If the articles live in the repo, I can feed it the structure, the code, and the existing posts together, and have it write the Markdown. What comes out is a PR diff I can review as-is, and I only have to fix the bits I want to fix.
Stick a CMS admin UI in the middle of that and the whole step gets annoying fast.

Astro content collections

Posts live as Markdown in src/content/posts/ and are read through Astro content collections.
The frontmatter looks like this.

---
title: "Post title"
description: "Copy used on the index and as the meta description"
publishDate: 2026-09-08
---

I made the filename the URL, so migrated posts keep the microCMS ID as the filename. src/content/posts/8vhec608u.md looks a bit silly, but I didn’t want to change URLs that were already public, so I left them.

The schema has draft, so a post is visible in npm run dev but dropped from the production build. I can push work in progress without worrying.

What the migration involved

I converted the HTML from microCMS’s rich editor into Markdown and poured it in.

After converting, I stripped tags from the original HTML and the generated HTML and compared the text, to make sure there was no diff. If I checked by eye I’d definitely drop something.

What that caught was bare URLs getting eaten by Markdown autolinks. In the privacy policy, https://ryo-suga.com（以下、「当サイト」と言います。）では、 stuffed everything through the Japanese after the full-width parenthesis into the href. I had to laugh. I rewrote that one as an explicit link.

microCMS’s rich editor also put target="_blank" on external links, so I wrote one plugin to get the same HTML out of Markdown. Current Astro uses Sätteri for Markdown, so it’s a hast plugin, not a rehype one.

Past me got in the way

The migration itself went fine, but the Cloudflare Pages build died with Node.js v16.19.0 is not supported by Astro!

The previous post says this:

For the Node.js version (LTS v18 doesn’t work at the moment), setting the NODE_VERSION environment variable to 16.19.0 got the build through.

That env var from past me was still there, so even after bumping Astro from 2 to 7 it was still trying to build on Node.js 16. Updating the env var on Pages fixed it.

Settings that only live in environment variables are forgotten three and a half years later. I learned that the hard way.

From here

The steps for writing a post are now: branch, add one Markdown file, open a PR. CI on the PR only checks that the build passes.

This post itself was written by pointing at the repo after the migration.
There’s a lot less busywork before I can start writing, so it would be nice if I posted a bit more often.