新規記事の作成コマンド、slug・カテゴリの仕様、front matter 全項目のリファレンス、下書き運用から公開までの流れをまとめた自分用マニュアル。
このサイトで記事を書くときの手順・仕様をまとめた自分用マニュアルです。記法やコンポーネントの詳細は各ガイド記事へのリンクで示し、この記事では執筆フロー全体と front matter の仕様に集中します。
新規記事の作成コマンド
ひな形の生成は npm run new-post で行います（scripts/new-post.mjs）。front matter と本文のテンプレートが入った MDX ファイルが作られ、プレビュー URL が表示されます。
ブログ記事
npm run new-post -- "記事タイトル" --slug my-post --category "Web Development" --tags a,b,c数学記事
npm run new-post -- "複素数の極形式" --slug polar-form --math --field complex-numbers --order 2オプション一覧
| フラグ | 必須 | 説明 |
|---|---|---|
--slug | 日本語タイトル時は必須 | URL に使う英数字スラッグ。英語タイトルなら自動生成される |
--category | ブログ記事で必須 | カテゴリ名（"Web Development" など。スラッグではない） |
--tags | 任意 | カンマ区切り（a,b,c）。数学記事の既定は ["math"] |
--math | 数学記事のとき | content/math-content/ にひな形を作る |
--field | --math で必須 | 分野スラッグ（notation / complex-numbers / quadratic-functions / limit / differentiation / integration） |
--order | 任意（既定 1） | 分野内の表示順・前後ページャの順序 |
同名ファイルが既にあるとエラーで止まるので、上書き事故は起きません。分野やカテゴリを増やしたときは、スクリプト内の CATEGORIES / MATH_FIELDS のリストも同期が必要です（lib/categories.ts / lib/math-fields.ts と対応）。
slug と URL・カテゴリの仕様
ブログ記事は「索引方式」
- URL は
/blog/<カテゴリのslug>/<ファイル名のslug>になります - カテゴリの真の源は front matter の
category（またはcategoryId）で、ファイルをどのフォルダに置いても URL は変わりません。content/blog/配下ならどこでも OK（慣例としてカテゴリ名のフォルダに置いています） - ファイル名（拡張子を除いた部分）がそのまま記事の slug になります
整合性はビルド時に検証され、次の場合はビルドが失敗して教えてくれます：
- カテゴリが未指定、または
lib/categories.tsのツリーで解決できない - 同一カテゴリ内で slug が重複して URL が衝突する
数学記事はフラット構成
- URL は
/math/<slug>（content/math-content/<slug>.mdx） - 分野（
field）はフォルダではなくメタデータです。分野ページ/math/section/<field>の一覧と前後ページャはfieldとorderから作られます
front matter リファレンス
ブログ記事（content/blog/**）
---
title: "記事タイトル"
date: "2026-07-05" # 公開日（一覧の並び順もこれ）
updated: "2026-07-06" # 更新日（任意。設定すると更新日として表示）
excerpt: "記事の要約。" # カード・検索・OGPの説明文
category: "Web Development" # カテゴリ名 or categoryId（必須）
tags: ["mdx", "writing"]
author: "ハルノスケ" # 省略時も「ハルノスケ」
draft: true # 下書き（後述。公開時は行ごと削除）
---全項目の詳細：
| 項目 | 型 | 説明 |
|---|---|---|
title | 文字列 | 記事タイトル |
date | "YYYY-MM-DD" | 公開日。ブログ一覧・前後ページャは日付降順 |
updated | "YYYY-MM-DD" | 更新日（任意）。内容に手を入れたら付ける運用 |
excerpt | 文字列 | 要約。省略すると本文の先頭 150 文字から自動生成される |
category / categoryId | 文字列 | どちらか必須。名前（"Web Development"）でも id/slug（"web-development"）でも解決される |
tags | 配列 | タグ。表記ゆれ（TypeScript/typescript など）は slug 単位で自動統合される |
author | 文字列 | 省略時 ハルノスケ |
draft | 真偽値 | true で下書き（後述） |
image | パス/URL | 構造化データ用の画像を差し替えたいときに指定。OGP・カード画像は指定が無くてもタイトルから自動生成（/og/blog/<cat>/<slug>.png） |
imageAlt | 文字列 | image の代替テキスト |
heroImage / heroAlt | パス/文字列 | 記事上部のヒーロー画像（任意） |
readTime | 数値 | 読了時間（分）。省略すると本文量から自動計算 |
layout | one-column / two-column | 予約項目。現在レイアウト切替には未使用 |
popularity | 数値 | コマンドパレット（検索）のサジェスト優先度。大きいほど上位 |
数学記事（content/math-content/）
ブログ用の項目に加えて（category は自動で Mathematics になるので不要）：
| 項目 | 型 | 説明 |
|---|---|---|
field | 文字列 | 所属分野の slug（必須級）。未設定は「未分類」扱いになり、分野一覧・前後ページャに載らない |
order | 数値 | 同じ分野内での表示順。前後ページャ（前の章・次の章）もこの順 |
下書き（draft: true）
front matter に draft: true と書くと：
- 本番ビルドから完全に除外されます（記事ページは 404、一覧・タグ集計・sitemap・RSS・検索・OG 画像・数式インデックスすべて対象外）。そのまま commit / push しても公開されません
npm run devでは普通に閲覧できます（執筆プレビュー用）- 書きかけでカテゴリ未設定でもビルドは落ちません
- 公開するときは
draft: trueの行を削除するだけ
執筆中のプレビュー
npm run dev # http://localhost:3000content/ 配下の MDX を保存するとリロード無しで自動反映されます。生成系（検索インデックス・OG 画像など）は npm run dev の起動時に自動実行されるので、個別に叩く必要はありません。
本文の書き方（各ガイドへのリンク）
本文は MDX（Markdown + コンポーネント）です。記法の詳細はそれぞれのガイドを参照：
-
基本的な Markdown 記法と表示例 → Markdown Showcase（MDXスタイル集）
見出し・リスト・表・引用・脚注・コードブロック・埋め込みなどの一覧
-
自作コンポーネントの使い方 → 自作コンポーネント使い方ガイド
コールアウト・
<Box>・<Indent>・<Annot>（注釈リスト）・文字色・数学ブロック（<Def><Thm>など）・相互参照<MathReference>・再掲載<MathEmbed>・<LinkCard>・[[toc]]ほか、すべて import 不要 -
数式の書き方 → 数式レンダリングガイド
$...$/$$...$$の基本、場合分け・複数行、サイト共通マクロ（\rotin\pink）、実践サンプル集 -
サイトのカスタマイズ（カテゴリ追加・デザイントークン） → カスタマイズガイド
VS Code スニペット
.vscode/ にスニペットが入っているので、MDX 編集中に補完が効きます：
- コンポーネント名（
annotboxdefなど）→ 使い方ドキュメント付きのひな形を挿入 mref-→ 実在する定義・定理の id から<MathReference>を補完membed-→ 同じく<MathEmbed>を補完
mref- / membed- の候補は数式インデックスから自動生成されるため、実在する id しか出ません。
数学の定義・相互参照の運用ルール
<Def>/<Thm>などのidはサイト全体で一意。重複するとビルドが失敗します<MathReference id="...">が存在しない id を指すと、これもビルドが失敗します（宙ぶらりん参照の防止）- 原典（定義の正本）は数学記事側に置くのが基本。ブログ記事内で書いた定義も参照はできますが、育ってきたら数学記事へ昇格させる運用です
公開までの流れ
draft: trueを外す（付けていた場合）- 必要なら
npm run buildでローカル検証（参照整合性・カテゴリ解決などが全部チェックされる） - commit して push
push すると GitHub Actions がビルド → Cloudflare Workers へ自動デプロイします。OG 画像・検索インデックス・数式インデックスはビルド時に自動再生成されるので、手動で更新するものはありません。
公開前チェックリスト
-
title/date/excerpt/category（数学はfield/order）が入っている -
draft: trueを外した - 定義を書いたら id の重複がないか（ビルドが教えてくれる）
- 内容を更新した既存記事なら
updatedを今日の日付に