MDX Error Prevention Guide
概要
このドキュメントは、Docusaurus WIKIでMDXコンパイルエラーを防ぐための包括的なガイドです。日本語技術文書、パフォーマンス仕様、優先度表記などでよく発生するエラーパターンと対策を網羅します。
🚨 よく発生するMDXエラーパターン
1. 文字制限エラー（最も頻繁）
エラーメッセージ例：
Unexpected character `1` (U+0031) before name, expected a character that can start a name, such as a letter, `, or `_`
原因：MDXでは < の後に数字が来ると、JSXタグの開始と誤認識される
問題のあるパターン：
❌ NG: - UID埋め込み処理: <10ms/写真
❌ NG: - 応答時間: <50ms以下
❌ NG: - 成功率: <99.9%達成
❌ NG: - パフォーマンス: <10ms/リクエスト
正しい書き方：
✅ OK: - UID埋め込み処理: 10ms未満/写真
✅ OK: - 応答時間: 50ms以下
✅ OK: - 成功率: 99.9%未満を達成
✅ OK: - パフォーマンス: 10ms未満/リクエスト
✅ OK: - UID埋め込み処理: `<10ms`/写真（バッククォートで囲む）
2. 優先度表記エラー
問題のあるパターン：
❌ NG: 1. **P0**: <重要機能> (数字の後の<が問題)
❌ NG: - **P1**: <機能名>実装
正しい書き方：
✅ OK: 1. **P0**: 重要機能
✅ OK: 1. **P0**: `<重要機能>`（バッククォートで囲む）
✅ OK: - **P1**: 機能名実装
3. HTMLタグの誤認識
問題のあるパターン：
❌ NG: コスト: <$0.03以下
❌ NG: 処理時間: <100ms
❌ NG: データ: <1GB
正しい書き方：
✅ OK: コスト: 0.03ドル未満
✅ OK: 処理時間: 100ms未満
✅ OK: データ: 1GB未満
✅ OK: コスト: `<$0.03`以下（バッククォート使用）
🛡️ 文字制限とMDX安全ルール
危険な文字組み合わせ
<数字: 最も危険。JSXタグと誤認識<英字: HTMLタグと誤認識される可能性{数字または{英字: JSX式と誤認識</: 終了タグと誤認識
安全な表記方法
パフォーマンス仕様の書き方
✅ 推奨方法：
- 応答時間: 10ms以内
- 処理速度: 50ms以下
- 成功率: 99.9%以上
- メモリ使用量: 1GB未満
✅ バッククォート使用：
- 応答時間: `<10ms`
- 処理速度: `<50ms`
- 成功率: `>99.9%`
- メモリ使用量: `<1GB`
優先度とコストの書き方
✅ 推奨方法：
1. **P0優先**: Order ID統一（1週間）
2. **P1対応**: ハッシュ検証（3日）
- 月額コスト: 0.03ドル以下
- 実装期間: 1週間以内
✅ コードブロック使用：
1. **P0**: `<重要機能>`実装
- コスト: `<$0.03`/月
⚡ 即効性のある修正方法
一括置換パターン
プロジェクト全体で以下の置換を実行：
# 危険パターンの一括修正
find wiki/docs -name "*.md" -exec sed -i '' 's/<\([0-9]\)/\1未満/g' {} \;
find wiki/docs -name "*.md" -exec sed -i '' 's/<\$\([0-9.]*\)/\1ドル未満/g' {} \;
find wiki/docs -name "*.md" -exec sed -i '' 's/<\([0-9.]*\)ms/\1ms未満/g' {} \;
手動修正チェックリスト
ファイル編集時に以下をチェック：
-
<+ 数字 の組み合わせがないか -
<+ アルファベット が意図しないHTMLタグになっていないか - パフォーマンス仕様で
<を使用していないか - 優先度表記で
<が混入していないか
🔍 テスト戦略
ローカルテスト
# MDXエラーをローカルで事前検出
cd wiki
npm start
# ビルドテストでエラー検出
npm run build
CI/CDでの自動検出
# ビルド前の事前チェック
npm run build --silent
if [ $? -ne 0 ]; then
echo "MDXエラーを検出しました"
exit 1
fi
問題行の特定方法
エラーメッセージから問題箇所を特定：
Line: 364, Column: 15
# 特定行の確認
sed -n '364p' problematic-file.md
# 前後5行の確認
sed -n '359,369p' problematic-file.md
📋 安全な書式設定ルール
技術仕様の記述
✅ 安全な書式：
## パフォーマンス目標
- UID埋め込み処理: 10ms以内/写真
- 三点照合: 50ms以内/注文
- 全写真検証: 500ms以内/注文（10枚想定）
- 月額コスト増: 0.03ドル以下
## 実装優先順位
1. **P0優先**: Order ID統一 + D1ステータス管理（1週間）
2. **P0優先**: Firebase UID埋め込み + 三点チェック（1週間）
3. **P1対応**: SHA-256ハッシュ記録・検証（3日）
4. **P1対応**: 工場での全写真UID照合（1週間）
数値とパーセンテージ
✅ 安全な数値表記：
- 成功率: 99.9%以上
- エラー率: 0.1%以下
- 可用性: 99.99%
- レスポンス時間: 100ms以内
- スループット: 1000req/sec以上
コードブロックの使用
技術的な表記が複雑な場合はコードブロックを活用：
```
パフォーマンス仕様:
- 処理時間: <10ms
- メモリ使用量: <1GB
- CPU使用率: <50%
```
🚨 緊急時の対応
エラー発生時の対応手順
-
エラー行の特定
# エラーメッセージから行番号を確認
sed -n '[行番号]p' [ファイル名] -
問題文字の特定
# < + 数字 パターンを検索
grep -n '<[0-9]' [ファイル名] -
即座修正
# 緊急時の一時修正（バッククォート追加）
sed -i '' 's/<\([0-9]\)/`<\1`/g' [ファイル名] -
ビルド確認
cd wiki && npm run build
よくある緊急修正パターン
# パターン1: パフォーマンス仕様
sed -i '' 's/<\([0-9.]*\)ms/\1ms未満/g' file.md
# パターン2: コスト表記
sed -i '' 's/<\$\([0-9.]*\)/\1ドル未満/g' file.md
# パターン3: パーセンテージ
sed -i '' 's/<\([0-9.]*\)%/\1%未満/g' file.md
📊 品質保証チェックリスト
編集前チェック
- 既存ファイルのMDX構文エラーがないか確認
- ローカルで
npm startでプレビュー確認
編集中チェック
-
<記号を使用する際はバッククォートで囲む - 数値 + 単位の表記で
<を避ける - HTMLタグと誤認識される表記を避ける
編集後チェック
-
npm run buildでエラーがないか確認 - デプロイ前にローカルプレビューで確認
- 本番デプロイ後の動作確認
🔧 自動化ツール
pre-commit hook設定
#!/bin/sh
# .git/hooks/pre-commit
find wiki/docs -name "*.md" -exec grep -l '<[0-9]' {} \; > /tmp/mdx_errors
if [ -s /tmp/mdx_errors ]; then
echo "MDXエラーの可能性があるファイル:"
cat /tmp/mdx_errors
echo "修正してからコミットしてください"
exit 1
fi
VS Code設定
// .vscode/settings.json
{
"editor.rulers": [80],
"editor.renderWhitespace": "all",
"files.trimTrailingWhitespace": true,
"markdown.validate.enabled": true
}
🎯 ベストプラクティス
1. 予防的記述
- 数値比較では「以内」「以下」「未満」を使用
<>記号は原則としてコードブロック内でのみ使用
2. 一貫した表記
- プロジェクト全体で統一した数値表記ルールを採用
- スタイルガイドに従った記述を心がける
3. 段階的確認
- ローカル確認 → ビルドテスト → デプロイ
- 各段階でエラーチェックを実施
4. チーム共有
- このガイドをチーム全体で共有
- エラーパターンを発見したら随時更新
最終更新: 2025-08-23
対象: Docusaurus v3.x + MDX
言語: 日本語技術文書対応