はじめに
ブログ原稿の保存形式を何にするかは、自動化全体の天井を決めます。最初に選んだ形式が、後段の変換ロジック、構造化データの実装難易度、AIとの連携しやすさを左右するからです。
私が選んだのはHTML本文＋YAMLフロントマターでした。一般的な選択肢である「Markdown一本」を見送った理由と、HTML+YAMLにすることで得た自由度を、この記事で記録します。
原稿フォーマットの三択
ブログ原稿の保存形式は、現実的には三つに絞られます。
選択は「自分にとって譲れない一点」で決まります。私の場合、譲れなかったのはバージョン管理とAI編集のしやすさでした。ブロックエディタはこの時点で消えました。残る二つから、どちらを選ぶかが本当の論点です。
なぜMarkdownを選ばなかったか
Markdownは書きやすさで圧倒的です。それでも見送ったのは、ブログ記事に求める要素がMarkdownの文法で素直に表現できない場面が多すぎたからです。
具体的に困る場面を挙げると、
- 商品紹介ボックス（Rinkerショートコード）の挿入
- 構造化データ（JSON-LD）の埋め込み
- アコーディオン、タブ、注釈ボックスなどのリッチUI
- 画像の細かい指定（alt、loading属性、figure要素）
- 内部リンクのrel属性指定
Markdownで書こうとすると、結局HTMLを混ぜて書くことになります。混ざった結果、Markdown部分とHTML部分が入り乱れる原稿は、機械的にパースしにくくなります。
最初からHTMLで書けば、この分岐は消えます。書きやすさは確かに落ちますが、変換レイヤーの単純さと引き換えなら受け入れられる、と判断しました。
もう一点、Claude Codeで原稿を編集する場合の挙動も決め手になりました。Markdownの拡張記法は実装によって解釈が分かれます。HTMLは仕様が明確で、AIに編集を任せても結果がぶれにくい。長期運用する自動化基盤では、この仕様の明確さが効いてきます。
YAMLフロントマターに何を入れるか
原稿の冒頭にYAMLブロックを置いて、記事に紐づくメタデータをすべてここに集約します。本文の中にメタデータが散らばらないことが、後段の機械処理の前提です。
ポイントは、人間が書いて意味のあるものだけを入れることです。生成可能な情報（記事のwords countや読了時間など）は入れません。それらは変換時に自動で算出するか、表示時にJavaScriptで計算します。
フロントマターに入れる情報の判断基準は二つです。
- 執筆者が指定しないと決まらないか：カテゴリ・タグ・構造化データ種別はYes
- 本文を読んでも自動で決められないか：商材ID、hreflangはYes
この二つを満たすものだけがフロントマター行きで、残りは本文か変換ロジックに置きます。
人間が書く領域と機械が読む領域
HTML+YAML方式の核心は、書き手と機械の役割分担を物理的にファイル内で分けたことです。
書き手が本文で頑張るのはHTML部分だけ。フロントマターは「設定ファイル」と割り切ります。一方、機械（変換スクリプト、AI、テンプレートエンジン）はフロントマターを参照して機械的な処理を完結させ、本文には触らない。
この境界を厳密に守ると、執筆中に余計なことを考えずに済みます。SEO設定を本文に埋め込もうとしたり、構造化データを手書きしようとする誘惑がなくなる。境界が明示されているから境界を守れる、という構造です。
逆に、ブロックエディタやNotionのように、コンテンツとメタデータが画面上で区別しづらいツールでは、この分離が崩れていきます。一年運用するとメタデータの粒度がバラついて、検索精度や構造化データの効果が落ちる、というのが他のブロガーから聞く失敗パターンです。
設計時に却下した代替案
主な却下案はMarkdownでしたが、もう一つだけ検討した案を残します。
案：MDX（Markdown + JSXコンポーネント）
MarkdownにReactコンポーネントを埋め込めるMDXも候補でした。リッチUIをコンポーネント化して再利用できる魅力があります。
却下した理由は、WordPress配信との不整合です。MDXはNext.jsやAstroなど静的サイトジェネレーターを前提にした形式で、WordPressのテーマ・プラグインエコシステムとは噛み合いません。Reactランタイムを別途読み込ませる構成も、表示速度とSEOの観点で現実的ではありませんでした。
新規にヘッドレス構成で作るならMDXは強い選択肢ですが、既存WordPressに乗せる前提では合いません。
案：JSON原稿
機械処理に最適化するなら、原稿そのものをJSONで持つ案も理屈の上ではあります。
却下した理由は単純で、人間が書けないためです。書き手が直接書く形式である以上、書きやすさは譲れません。JSONは変換後の中間形式としては使いますが、原稿の保存形式にはしません。
このシリーズで何度も戻ってくる原則
ここまでに繰り返し出てきた原則を明示化しておきます。機械が読みやすいフォーマットと、人間が書きやすいフォーマットを、無理に一つにしない。一つのファイル内でも、領域を分ければ両立できます。
これはCLAUDE.md三層構造（第2回）にも、この後扱うwp_import.pyの設計（第4回）にも、同じ形で出てきます。
次回予告
次回からは二回連続で wp_import.pyの実装解説 を扱います。前編はHTMLとYAMLの分解、画像参照の置換、JSON-LDの生成まで。後編はRinkerショートコード展開、REST API投稿、エラー処理、冪等性の確保まで。原稿レイヤーから連携レイヤーへ橋渡しする部分のコードを、設計判断とあわせて解説します。
このシリーズで紹介する設計は、執筆時点の各ツールバージョンに基づきます。Claude Code、MCP、WordPress、各種APIは仕様変動が大きいため、最新ドキュメントとの照合をおすすめします。
