このサイトで記事を書くときの手順・仕様をまとめた自分用マニュアルです。記法やコンポーネントの詳細は各ガイド記事へのリンクで示し、この記事では**執筆フロー全体と front matter の仕様**に集中します。 [[toc]] ## 新規記事の作成コマンドひな形の生成は `npm run new-post` で行います（`scripts/new-post.mjs`）。front matter と本文のテンプレートが入った MDX ファイルが作られ、プレビュー URL が表示されます。 ### ブログ記事 ```bash npm run new-post -- "記事タイトル" --slug my-post --category "Web Development" --tags a,b,c ``` ### 数学記事 ```bash 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/`（`content/math-content/.mdx`） - 分野（`field`）はフォルダではなく**メタデータ**です。分野ページ `/math/section/` の一覧と前後ページャは `field` と `order` から作られます ## front matter リファレンス ### ブログ記事（`content/blog/**`） ```yaml --- 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//.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` の行を削除するだけ ## 執筆中のプレビュー ```bash npm run dev # http://localhost:3000 ``` `content/` 配下の MDX を保存すると**リロード無しで自動反映**されます。生成系（検索インデックス・OG 画像など）は `npm run dev` の起動時に自動実行されるので、個別に叩く必要はありません。 ## 本文の書き方（各ガイドへのリンク）本文は MDX（Markdown + コンポーネント）です。記法の詳細はそれぞれのガイドを参照： - **基本的な Markdown 記法と表示例** → [Markdown Showcase（MDXスタイル集）](/blog/web-development/mdx-showcase) 見出し・リスト・表・引用・脚注・コードブロック・埋め込みなどの一覧 - **自作コンポーネントの使い方** → [自作コンポーネント使い方ガイド](/blog/web-development/component-guide) コールアウト・``・``・``（注釈リスト）・文字色・数学ブロック（`` `` など）・相互参照 ``・再掲載 ``・``・`[[toc]]` ほか、**すべて import 不要** - **数式の書き方** → [数式レンダリングガイド](/blog/technology/math-rendering-guide) `$...$` / `$$...$$` の基本、場合分け・複数行、サイト共通マクロ（`\rotin` `\pink`）、実践サンプル集 - **サイトのカスタマイズ（カテゴリ追加・デザイントークン）** → [カスタマイズガイド](/blog/web-development/customization-guide) ### VS Code スニペット `.vscode/` にスニペットが入っているので、MDX 編集中に補完が効きます： - コンポーネント名（`annot` `box` `def` など）→ 使い方ドキュメント付きのひな形を挿入 - `mref-` → 実在する定義・定理の id から `` を補完 - `membed-` → 同じく `` を補完 `mref-` / `membed-` の候補は数式インデックスから自動生成されるため、**実在する id しか出ません**。 ## 数学の定義・相互参照の運用ルール - `` / `` などの `id` は**サイト全体で一意**。重複するとビルドが失敗します - `` が存在しない id を指すと、これも**ビルドが失敗**します（宙ぶらりん参照の防止） - 原典（定義の正本）は数学記事側に置くのが基本。ブログ記事内で書いた定義も参照はできますが、育ってきたら数学記事へ昇格させる運用です ## 公開までの流れ 1. `draft: true` を外す（付けていた場合） 2. 必要なら `npm run build` でローカル検証（参照整合性・カテゴリ解決などが全部チェックされる） 3. commit して push push すると GitHub Actions がビルド → Cloudflare Workers へ自動デプロイします。OG 画像・検索インデックス・数式インデックスはビルド時に自動再生成されるので、**手動で更新するものはありません**。 ### 公開前チェックリスト - [ ] `title` / `date` / `excerpt` / `category`（数学は `field` / `order`）が入っている - [ ] `draft: true` を外した - [ ] 定義を書いたら id の重複がないか（ビルドが教えてくれる） - [ ] 内容を更新した既存記事なら `updated` を今日の日付に

ブログ執筆ガイド（記事作成から front matter・公開まで）