microCMSをやめてMarkdown+gitへ移行｜47記事の脱CMSを安全に進める

こんにちは、wandです！

このブログは2025年1月に AWS + Next.js + microCMS の Jamstack 構成で立ち上げました。

AWS + Next.js + microCMS で Jamstack ブログシステムを構築しましたAWS、Next.js、microCMSを活用した Jamstack ブログシステム構築の詳細2025-01-04

それから1年半あまり、2026年8月に microCMS をやめて、記事を Markdown + git で持つ構成に移行しました。
47記事と画像431枚をまるごと引っ越して、公開 URL も広告の位置もアフィリエイトリンクも1つも変えずに切り替えています。

この記事では、脱CMSに踏み切った理由と、壊さずに移行するために何を機械で確かめたか、
そして移行してから何が楽になったかを書きます。
ヘッドレスCMS から Markdown への移行を考えている方の参考になれば幸いです。

なぜ microCMS をやめたのか

きっかけは、書き方が変わったことでした。

記事の下書きは手元の Markdown で作り、そのまま AI エージェントに書かせる流れになっていました。
できあがった原稿をリッチエディタに貼り直す作業だけが残っていて、管理画面を開く理由が「貼るため」しかない状態です。

API で流し込むこともできます。ただ、原稿は手元にあり、公開は静的ビルドです。
どう置いても CMS は経由地が1つ増えるだけになっていました。

もう1つは無料枠の上限です。
Hobby プランはデータ転送量が 20GB/月で、公式の料金ページにあるとおり
超えるとAPIが停止します。記事も画像も CMS から配信していたので、増えるほどこの上限に近づきます。

47記事を Markdown に一括変換する

移行後の記事は、リポジトリの content/{slug}/index.md に置いています。
ディレクトリ名がそのまま公開 URL の slug です。

content/{slug}/
├── index.md      本文と frontmatter
├── shikkui-before.webp   元画像
└── embeds.json   リンクカードの中身

frontmatter は YAML で、CMS の項目をそのまま持ち込みました。

---
title: "記事タイトル"
description: "概要"
date: "2026-08-20T13:00:00+09:00"    # microCMS の publishedAt
updated: "2026-08-21T09:30:00+09:00" # microCMS の revisedAt
tags: [gardening]
thumbnail: "/images/{slug}/shikkui-before.webp"
use_toc: true
---

変換スクリプトを書く前に、本文 HTML を全件集計しました。
「だいたいこんな感じ」で書き始めると、必ず取りこぼします。
対象は47記事に相互リンク集を足した48件で、以下の件数はその48件の合計です。

text-align の190箇所は、内訳が start 184 / left 6 で、中央寄せは1件もありませんでした。
どちらもブラウザの既定の揃え方で、エディタが余計に付けていただけです。捨てて問題ありません。

決めたことは4つです。

• 言語指定なしのコードブロック44件は text で固定する。 自動推定は誤爆するので、気になったものだけ後から手で直す
• 見出しの id は、本番で配信されている値をそのまま焼き込む。 CMS 側の id 生成規則が読み解けなかったため、
  自前で採番すると目次と外部からのアンカーリンクが黙って壊れます
• スクリプトは冪等にする。 何度でも回して差分ゼロに追い込めること
• 1記事1コミットで入れる。 47記事を1コミットにすると差分が読めません

配信中の本番 HTML を「正」にして機械比較する

ここがこの移行のいちばんの山でした。

何と突き合わせるかで、見つかる事故の種類が変わります。
このブログでは、CMS からダンプした記事データではなく、いま配信されている本番の HTML を正としました。

Lambda@EdgeとCognitoでJamstackアプリの開発環境に認証を実装するJamstackブログの開発環境に認証を追加した方法を解説。Lambda@EdgeとCognitoを活用し、低コストでセキュリティと利便性を両立。2025-02-02

ステージング環境には Cognito と Google 認証がかかっていて、取りに行くと認証へリダイレクトされます。
新しい側は手元でビルドした out/ をそのまま使い、デプロイせずに突き合わせました。

48ページを1ページずつ比較した結果がこちらです。

最終的に、説明できない差分は0件になりました。

広告の位置は、AdSense を実装した記事で書いたとおり本文の途中に差し込んでいます。
数だけでなく直前の見出し id まで一致させたのは、位置が1段ずれても数は合ってしまうからです。

意図して変えたぶんは、比較スクリプト側に例外として持たせました。
このとき向きを固定したのがポイントです。広告の差込先やアフィリエイトの表示が「増える」のは通しても、
「消える」のは何があっても通さない、という書き方にしています。

移行して変わったこと

手元の Markdown がそのまま公開される本文になりました。
管理画面に貼り直す工程が無いので、原稿が2箇所に分かれません。
推敲もレビューも content/{slug}/index.md の上で終わります。

記事の変更は Pull Request で上がってきます。
写真が1枚落ちている差分にも、その行にコメントを付けて返せます。
どの行の話なのかを言葉で説明せずに渡せるのは、管理画面には無かったところです。
PR のレビューを読み上げさせて、耳で片付ける形にした話は別に書きました。

【プロンプト配布】PR レビューを AI に読み上げさせて、ながら作業で片付ける溜まった PR レビューを耳で聞いて「OK」と返すだけにしました。2026-09-01

よくある質問

Q. 記事の URL は変わりましたか？

変えていません。/articles/{slug}/ のままです。

Q. 移行にどれくらいかかりましたか？

計画づくりから Claude Code (Opus 5) に任せ、まずフェーズごとの issue に分解させました。
最初の起票から、本番切替のコミットが main に入るまで約19時間です。
夜をまたいだ経過時間で、実作業時間の合計ではありません。

Q. 画像を git に入れて重くなりませんか？

思ったほどではありませんでした。
CMS 側にあった元画像431枚は合計94MB でしたが、長辺2000px の WebP に正規化して取り込んだ結果、
リポジトリに入ったのは合計26MB・平均62KBです (2026年8月21日現在)。

ただし WebP は git の圧縮でほとんど縮まないので、置いた分がそのまま増えます。
本文の写真は表示する幅どおりの大きさで置き、大きく焼くのはサムネイルの1枚だけ、という運用にしています。

Q. ヘッドレスCMS はやめたほうがいいですか？

そうは思いません。私の場合は、書く場所が管理画面から手元に移ったからやめただけです。
入稿する人が複数いるなら、管理画面がある構成のほうが噛み合うはずです。

まとめ

microCMS から Markdown + git への移行を振り返ると、要点は3つでした。

移行そのものより、移行を確かめる道具のほうに時間をかけるのが結局は近道でした。
比べる相手は、手元のデータではなく、いま読者に届いている HTML です。

引っ越しを考えているなら、まず「何が変わっていないと困るか」を1行ずつ書き出してみてください。
その一覧が、そのまま比較する道具の仕様になります。

このブログは今日も同じ URL で動いています。作り替えても、読者から見た景色が変わらないのがいちばんです。