GitHubに置くだけのブログ自動読み込みを実運用して分かったこと ──「動く」と「使える」は別だった
GitHubに記事ファイルを置いたら、Next.jsのサイトが自動で拾って、一覧もサイトマップも勝手に増える。 これ、思想としてはかなり強いです。
正直、最初はこう思いました。
「記事を置いたら自動で反映されるブログ基盤が最適解では？」
実際に僕もそれをやりました。PoCとして動かすところまでは、わりと早い。
ただし、そこで終わりじゃなかった。
“思ったより簡単ではなかった”のは、技術が難しいからではなく、
運用に入った瞬間に「壊れ方」が露出するからでした。
- 自動化 = 楽
- Markdown/MDX = 正義
- 表示された = 運用できる
なぜそれが起きるか（構造）
PoCは「動くか」を見る。本番は「壊れても回るか」を問う
自動読み込みのPoCは、だいたいこうです。
「ファイルを置いた → 記事が出た → OK」
でも運用は違う。運用の問いはこうです。
「増え続ける記事を、壊さず、迷子にせず、原因不明にせず回せるか」
この差分が、見えないコストになります。 そしてこのコストは、たいてい“最後にまとめて請求”されます。
本当にキツいのは「壊れる」ことより「理由が分からない」こと
記事が崩れる・出ない・一覧だけ欠ける。 これ自体もキツいですが、よりキツいのは原因が分からない状態です。
つまり問題は「技術の欠陥」ではなく、設計の問題でした。 失敗を前提に設計されていないと、失敗した瞬間に調査コストが爆発します。
今回試した構成（事実だけ）
ここは評価しません。あくまで「何をやったか」だけを書きます。
- GitHubに記事ファイルを置く
- Next.js（App Router）で記事を自動検出する
- 自動インデックス（一覧生成）
- 自動サイトマップ（記事追加に追従）
- HTML / MDX の両対応を試行
PoC段階では「動く」までは到達できた。 ただしそれは「運用で回る」ことを意味しなかった。
PoCでは見えなかった問題が、運用で一気に露出する
記事は出る。でも壊れる
自動読み込みは「出す」こと自体はそこまで難しくない。 問題は、出た記事が一定の品質で出続けることでした。
- レイアウトが崩れる
- 表が崩れる（または横幅で破綻する）
- 見出し階層が崩れ、読みやすさとSEO/A11yが落ちる
自動取得が成功しているか失敗しているか分からない
これが一番きつい。 「表示されない」状態が起きたとき、なぜ表示されないのかが分からないと詰みます。
JSONの形が少し変わるだけでUIが壊れる
自動処理は、少しの揺れに弱い。 たとえばメタ情報のキーが揺れる、空文字やnullの扱いが揺れる、配列の形が変わる。 それだけで一覧表示や詳細ページが壊れます。
問題はフレームワークの限界ではなかった。 失敗を前提に設計していないと、運用で破綻する。
HTMLとMDXを両方使って分かった“向き・不向き”
ここで結論を急がない方がいいです。 HTMLとMDXは「優劣」ではなく「向いてる用途」が違う。
HTMLの強み（運用で効く）
- 壊れにくい（解釈の余地が少ない）
- 表が安定しやすい
- SEO/A11yを制御しやすい（見出し・代替テキスト・構造が固定できる）
MDXの強み（制作で効く）
- 書くのは楽
- コンポーネント連携がしやすい
MDXの落とし穴（自動化と相性が悪いところ）
- 表崩れが起きやすい（表現自由度が高い分、統制が難しい）
- 記法ミスが実行時まで分からないケースがある
- 自動処理（取り込み・変換・整形）で“例外ルール”が増えやすい
仮説：「記事数が増え、運用負荷が問題になるほど、HTMLの安定性が効く」。 逆に、表現の自由度が価値そのものならMDXが効く。
自動読み込みで重要なのは、技術より“壊れ方の設計”
自動化は、成功すると静かに価値を出します。 でも失敗すると、原因不明のまま時間を吸い続ける。 だから最初にやるべきは、派手な機能追加じゃなくて壊れ方の設計でした。
設計ポイント（ベストプラクティスの芯）
- 成功/失敗がUIで分かる（最低限、一覧やビルドで検知できる）
- JSONの形を1つに決める、または揺れを吸収する（互換レイヤーを持つ）
- 記事側に副作用を入れない（外部JS/CSSや不確実な依存を避ける）
- 表・画像・見出しのルールを最初に固定（自由を与えるほど運用が壊れる）
- 「楽に書ける」より「壊れない」を優先する
「書きやすさ」を先に最大化すると、後で「壊れにくさ」を取り戻すのが地獄になります。 なぜなら、記事が増えた後にルールを変えるのは“移行プロジェクト”になるからです。
最終的に採用したブログ基盤のベストプラクティス
ここで回収します。
「動く」だけなら色々できる。でも僕が欲しかったのは“使える”状態でした。
- HTMLを“正”として扱う
- MDXは限定用途（表現が価値になるページだけ）
- 表は必ずHTML（崩れにくさを優先）
- 記事は単一ファイルで完結（依存を増やさない）
- 自動処理は「失敗前提」で設計（失敗を検知できる形にする）
自動化で得たいのは「楽」ではなく、 書くことに集中できる状態です。 その状態は、最初のルール固定でほぼ決まる。
この方式が向いているか判断するチェックリスト
採用するかどうかは、あなたが決めていい。 ただし、判断に必要な論点だけはここに置いておきます。
チェック（Yes/NoでOK）
- 記事数は増える（増え続ける）見込みがある
- 外部連携（RSS/取り込み/変換/自動分類など）がある
- 表や図が多い（崩れると致命傷）
- 将来、書く人が自分以外になる可能性がある
- 「表示されない理由が分からない」状態を許容できない
| 状況 | おすすめ | 理由 |
|---|---|---|
| 記事が増える / 運用負荷が怖い | HTML正 + ルール固定 | 壊れにくさと再現性が効く |
| 表や構造が重要（仕様書・比較表など） | 表はHTML固定 | 崩れが運用事故になる |
| 表現の自由度が価値（凝った演出・埋め込み） | MDX限定採用 | 自由のコストを払える範囲で |
| とにかく早く書きたい（短命コンテンツ） | MDX寄りも可 | 運用寿命が短いなら移行コストが小さい |
意思決定フロー（文章）
- 記事が増えるか？ → 増えるなら「壊れにくさ」を優先する
- 表や構造が多いか？ → 多いなら表はHTML固定
- 失敗検知が必要か？ → 必要ならUI/ビルドで成功/失敗を見える化する
- 自由度が価値か？ → 価値ならMDXは限定用途で使う
- ルールを固定できるか？ → 固定できないなら自動化のコストが上がる
まとめ
自動化は目的ではありません。
「書くことに集中できる状態」を作るための手段です。
その状態を作る鍵は、技術選定より最初のルール固定でした。
「楽に書ける」より「壊れない」。ここを先に決めると、後がずっと楽になります。