telosh.log で MDX を書きながら運用する：frontmatter と公開の流れ

コードを書く人にとって、ブログの執筆もまたワークフローです。リポジトリに MDX を置く構成では、「どこに何を書けば一覧・SEO・課金に一貫して効くか」を最初に揃えておくと、あとからの手戻りが減ります。

ファイルの置き場とスラッグ

記事は content/posts/ 以下の .mdx です。ファイル名（拡張子除く）がそのまま URL のスラッグになります。

• 英数字とハイフンを基本にする
• 大文字小文字は運用で統一（URL はケースに依存しうるため）
• 既存記事と被らない名前を付ける

スラッグに .. やパス区切りが紛れ込むと、意図しないパス読み出しの余地が出るため、サーバー側で弾く前提で、執筆側でも変な文字は避けます。

frontmatter で決めること

よく使うフィールドは次のとおりです。

フィールド	役割
title	記事タイトル（一覧・OG・ページ見出し）
date	公開日（並び順に直結）
description	短い要約（メタディスクリプション）
categories	大分類（サイト内のカテゴリページ）
tags	細かいラベル（検索・関連付け）
draft	true のとき本番ビルドでは一覧から除外（開発時は表示可）
premium	有料記事にするか
priceJpy / stripePriceId	有料時の Stripe Price の解決

description は 一文で記事の約束を書くと、一覧カードや検索結果で読者に親切です。タイトルの繰り返しだけになる場合は、補足情報を足します。

無料記事と有料記事の違い（執筆者が触る範囲）

無料記事は、従来の Markdown と同じ感覚で 本文をそのまま書けばよいです。

有料記事にするときは、次をセットで確認します。

1. frontmatter に premium: true と、段階価格なら priceJpy（または直接 stripePriceId）
2. 環境変数に、対応する STRIPE_PRICE_JPY_* などが入っているか（プロジェクトのスキル・スクリプト参照）
3. 一覧に載るデータは本文が空になる設計のため、リード文や要約は description とタイトルで完結させやすい

「有料にしたのに一覧の検索で本文がヒットしない」は仕様に近い挙動なので、重要語はタイトル・タグ・説明に載せる癖が効きます。

下書きと本番の切り替え

draft: true は 本番では非表示、開発環境では確認できる、という二段構えです。プレビューデプロイで記事だけ先に確認したいときに便利です。

有料記事の Price は、本番カタログに載せない下書き用 Price と混同しないよう、運用ルールを決めておくと安全です（誤って本番 Checkout に繋がないため）。

執筆中に便利なコマンド（例）

プロジェクトに用意されているスクリプトは、package.json とスキル文書を参照してください。例として次のような作業があります。

• 記事メタの価格まわりを JSON で吐き出して差分確認する
• Stripe 側の段階 Price を一括作成し、.env に貼る

まとめ

• ファイル名＝スラッグを意識する
• frontmatter は読者向けメタとシステム向けフラグの両方
• 有料記事は本文が一覧検索に乗らない前提で、タイトル・説明・タグを厚くする
• draft で本番に出さずに検証する

このブログ自体が実験場なので、ルールは記事とスキルを更新しながら緩やかに変えていくつもりです。