• #nuxt
  • #content
  • #mdx
  • #setup
未分類

Nuxt Content + MDX サイトの初期構築手順

ゴール

  • Nuxt 3 + @nuxt/content で Markdown / MDX を公開できるサイトを構築する。
  • Cloudflare Pages へデプロイできるドキュメント駆動構成を採用する。
  • 将来的にバックエンド API や追加サービスを組み込めるディレクトリ構成を整える。

必要な環境

  • Node.js 22.6 以上（Volta で volta pin [email protected] 推奨）
  • pnpm 10 系（packageManager に [email protected] を指定）
  • Windows 10/11 + PowerShell 7、もしくは同等のシェル環境
  • リポジトリ: C:\Users\numbe\Git_repo\mdx-playground

セットアップ手順

  1. 作業ツリーを確認し、既存変更をコミットまたは退避する。
  2. 主要ディレクトリを作成。 
    New-Item -ItemType Directory -Path apps,packages,docs -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Path apps/web -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Path apps/api -ErrorAction SilentlyContinue
  3. apps/web で Nuxt プロジェクトを初期化。 
    cd apps/web
npx nuxi@latest init . --force
pnpm install
  4. @nuxt/content と MDX 関連プラグインを追加。 
    pnpm add @nuxt/content remark-gfm remark-math
  5. apps/web/nuxt.config.ts を編集し、documentDriven、sqliteConnector、sources.memo を設定する。
  6. apps/web/content.config.ts に pages コレクションを定義し、すべての Markdown/MDX を読み込めるようにする。
  7. content/ 配下に初期記事と index.mdx を作成する。

推奨ディレクトリ構成

mdx-playground/
├─ apps/
│  ├─ web/    # Nuxt 3 + @nuxt/content フロントエンド
│  └─ api/    # バックエンド用 Nitro など（将来的に追加）
├─ packages/  # 共有 UI や設定パッケージ
├─ memo/      # 執筆メモ（Content ソースとしても利用）
├─ docs/      # 運用・設計ドキュメント
└─ tools/     # スクリプトや補助ツール

開発とデプロイ

  • ローカル開発: pnpm dev -- --port 3000
  • 静的生成: pnpm run build または npx nuxi generate
  • Cloudflare Pages へは GitHub Actions を利用し、web と api を個別ワークスペースとしてビルドする。

トラブルシュートのヒント

  • Nuxt Content のクエリは queryCollection() を利用し、.path() などで条件を明示する。
  • pnpm install を実行してから依存追加コマンドを実行し、.pnpm 情報を最新化する。
  • SQLite ネイティブ接続を有効にするため、experimental.sqliteConnector = "native" を指定し、Windows では Node.js 22.6 以上を利用する。