開発ドキュメント

Architecture & Developer Guide

本リポジトリは、数式およびインタラクティブなグラフィックスを含む静的サイトを構築・配信するためのシステムです。本稿では、採用している技術スタックと、コンテンツ執筆者向けのコーディングガイドラインを定義します。

1. 技術スタック (Tech Stack)

フロントエンド構成

Framework: Next.js (App Router)
Content: MDX (@next/mdx)
Styling: Tailwind CSS

本プロジェクトでは動的なサーバーサイドレンダリングを行わず、output: 'export' を指定した完全な静的サイト生成（SSG）によるHTMLエクスポートを行っています。UIのスタイリングにはTailwind CSSを用い、ダークモード対応を含めたユーティリティクラスベースの設計を採用しています。

数式・グラフィックス

Math: KaTeX (remark-math, rehype-katex)
Graphics: React (SVG) / Three.js (@react-three/fiber)

数式の組版処理にはKaTeXを使用し、ビルド時に静的なHTML/CSSへと変換することで初回描画時のレイアウトシフト（CLS）を防止しています。グラフや図版はラスター画像を用いず、ReactコンポーネントとしてのSVGまたはWebGL（Three.js）を用いた動的描画を行っています。

デプロイメントパイプライン

インフラには Cloudflare Pages を採用しています。 GitHubの対象ブランチ（例: main）へコミットがプッシュされると、Cloudflareのビルド環境内でNext.jsのビルドがトリガーされ、生成された静的アセットがグローバルエッジネットワークにデプロイされます。

2. ローカル開発環境のセットアップ

リポジトリをクローン後、以下のコマンドで依存関係のインストールと開発サーバーの起動を行います。なお、MDXコンパイラとTurbopackの競合を回避するため、起動時は必ず --webpack フラグを付与してください。

bash

# 依存パッケージのインストール
npm install

# 開発サーバーの起動（Webpackモード）
npm run dev --webpack

起動後、ブラウザで http://localhost:3000 にアクセスして表示を確認します。

3. コーディングガイド (How to author)

コンテンツの執筆は、src/app/ 以下のディレクトリに page.mdx ファイルを作成して行います。当サイトでは、学術的構造を視覚化するために独自の MyBox コンポーネントを使用します。

MyBox コンポーネントの基本書式

MDXファイルの先頭でコンポーネントをインポートし、type と title を指定して使用します。

tsx

import { MyBox } from '@/components/MyBox';

<MyBox type="D" title="速度の定義">
時間 $\Delta t$ あたりの移動距離が $\Delta x$ のとき、速度 $v$ は次のように表す。
$$
v = \frac{\Delta x}{\Delta t}
$$
</MyBox>

利用可能な BoxType 一覧

文脈に応じて以下の type を使い分けてください。

D (Definition): 定義、条文、公理など（最も強調されるスタイル）
F (Formula/Fact): 公式、法則、判例など
P (Proof): 導出過程、理由付け、論証など（枠線なしの控えめなスタイル）
G (Graph): 図解、SVGシミュレーションを囲むためのコンテナ

ネスト（入れ子）構造の記述

公式（F）の中にその導出過程（P）を含めるなど、MyBox は入れ子にして記述することが推奨されます。

tsx

<MyBox type="F" title="運動方程式">
$$
\boldsymbol{F} = m\boldsymbol{a}
$$

<MyBox type="P" title="導出">
運動量の時間変化率 $d\boldsymbol{p}/dt$ から導かれる...
</MyBox>
</MyBox>