開発資産MarkdownをMDX記事へ変換する作業フロー

はじめに

開発中に作ったメモやテンプレートは、そのままでは公開記事として読みにくいことがあります。短い箇条書き、案件固有の表現、内部向けの注意書きが混ざっているためです。

そこで、開発資産として残したMarkdownを、公開サイト向けのMDX記事へ変換する作業フローを決めておくと、記事化の品質が安定します。

この記事では、Codexで記事化作業を行うときの基本手順を整理します。

使う場面

開発資産フォルダ内のMarkdownを技術ブログへ出したい
既存メモを読者向けの記事構成に直したい
frontmatter、slug、関連リンクの付け方をそろえたい
AIエージェントに記事化作業を任せたい

基本フロー

記事化では、原本と公開用ファイルを分けて扱います。

技術スタック別フォルダのMarkdown
  |
  v
公開向けに文脈を補う
  |
  v
website/content/<category>/<slug>.mdx

原本側のMarkdownは、開発者やAIが再利用するための資産です。公開用のMDXは、読者が読んで理解し、必要なら実装へ進める記事です。

frontmatterの最小形

MDX記事には、次のfrontmatterを入れます。

---
title: "記事タイトル"
category: "codex"
slug: "website-mdx-article-workflow"
tags: ["Codex", "MDX", "技術ブログ"]
description: "記事一覧や検索結果に出す短い説明文"
date: "2026-05-20"
---

categoryは保存先フォルダと合わせます。slugはファイル名と合わせると、URLとファイル管理の対応がわかりやすくなります。

本文で補う内容

原本が短いメモの場合でも、公開記事では次の情報を補います。

| 観点 | 補う内容 | |---|---| | 課題 | 何に困っていたか | | 使う場面 | どんな案件や作業で使うか | | 実装 | コピペできるコードや手順 | | 判断 | どこまで共通化するか | | 注意点 | 公開リスク、ハマりどころ | | 関連導線 | 次に読む記事や用語 |

「コードだけ置く」のではなく、読者が採用判断できる形にすることが重要です。

検証観点

通常は記事追加後にビルド確認をします。

cd website
npm run build

確認するのは、MDX構文、frontmatter、記事一覧、カテゴリページ、記事詳細ページ、コードブロック、日本語表示です。

ただし、作業依頼で「buildはしない」と指定されている場合は、ビルドせずに変更ファイルと未検証であることを報告します。

注意点

原本Markdownを更新しても、公開サイトには自動反映されません
MDXだけを追加しても、原本側の資産一覧には増えません
顧客名、実パス、APIキー、個人情報は公開記事に入れません
新カテゴリを追加する場合は、サイト側のカテゴリ定義も確認します
文字化けして見える原本は、記事化前にUTF-8として読み直します

まとめ

開発資産MarkdownをMDX記事へ変換するときは、原本の意図を残しつつ、読者向けに課題、使う場面、実装、注意点、関連リンクを補います。

この流れを固定しておくと、Codexに記事化を任せる場合でも、単なるメモの貼り付けではなく、公開に耐える技術記事へ整えやすくなります。