mdx-sanitizer について
JSXの解析エラーを招く可能性があるMDXコンテンツを整えるスキルです。ドキュメントのビルドを保守する開発者向けに、同期時のサニタイズとコミット前・ビルド時の検証を行い、コードブロックは保護します。
主な機能
- 01競合する山括弧パターンの検出
- 02HTMLエンティティによるエスケープ
- 03コードブロックとインラインコードの保護
- 04確認・修正コマンドの提供
- 05コミット前とビルド時の検証連携
活用シーン
- 01ドキュメント内のTypeScriptジェネリクスを修正
- 02比較演算子によるMDXビルド失敗を防止
- 03コミット前に括弧の問題を確認
- 04スキル文書の同期時に内容をサニタイズ
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/mdx-sanitizerを入力して読み込まれたか確認します。
同梱ファイル.claude-plugin/plugin.json
詳細
MDX サニタイザー
山括弧、ジェネリクス、その他の競合するパターンが原因で発生する JSX の解析エラーを防ぐ、包括的な MDX コンテンツサニタイザーです。
問題
MDX 2.x では、エスケープされていない < と { は JSX 構文として扱われます。そのため、コンテンツに次のものが含まれているとビルドが失敗します。
- TypeScript のジェネリクス：
Promise<T>、Array<string>、Map<K, V> - 比較演算子：
<100ms、<=、>= - 矢印：
-->、<--、-> - 無効なタグ：文章中の
<link>、プレースホルダーの<tag> - 空の山括弧：
<>
ソリューションのアーキテクチャ
このスキルでは、3 層の防御を実装しています。
1. 同期時のサニタイズ（事前対策）
.claude/skills/ から website/docs/ への同期時にコンテンツをサニタイズします。
syncSkillDocs.ts- スキルのメインファイルsyncSkillSubpages.ts- リファレンスファイルdoc-generator.ts- 生成されたドキュメント
2. コミット前の検証（事後対策）
Git のコミット前フックが、コミット前に validate-brackets.js を使ってファイルを検証します。
3. ビルド時の検証（最終確認）
npm run validate:all が prebuild の一部として実行され、問題を検出します。
使い方
問題を確認する（ドライラン）
cd website
npm run sanitize:mdx
# or with verbose output
npm run sanitize:mdx -- --verbose
すべての問題を修正する
cd website
npm run sanitize:mdx -- --fix
# or shorthand
npm run fix:mdx
プログラム API
import { sanitizeForMdx, validateMdxSafety, isMdxSafe } from './lib/mdx-sanitizer';
// Sanitize content
const result = sanitizeForMdx(content, { useHtmlEntities: true });
if (result.modified) {
console.log(`Fixed ${result.issues.length} issues`);
fs.writeFileSync(path, result.content);
}
// Validate without modifying
const issues = validateMdxSafety(content, 'path/to/file.md');
// Quick check
if (!isMdxSafe(content)) {
// Handle issues
}
エスケープ方法
このサニタイザーでは、互換性を最大限に高めるために HTML エンティティを使用します。
| パターン | 元の表記 | エスケープ後 |
|---|---|---|
| 小なり記号 | < | < |
| 大なり記号 | > | > |
| ジェネリクス | <T> | &lt;T&gt; |
| 比較演算子 | <= | &lt;= |
コードブロック（``` または `）内のコンテンツは自動的に保護され、エスケープされません。
変更されたファイル
website/scripts/lib/mdx-sanitizer.ts- サニタイザーのコアモジュールwebsite/scripts/sanitize-mdx.ts- CLI ラッパーwebsite/scripts/syncSkillDocs.ts- 統合website/scripts/syncSkillSubpages.ts- 統合website/scripts/lib/doc-generator.ts- 統合website/package.json- npm スクリプト
検出するパターン
- 数字の前の小なり記号：
<100、<0.5ms - 比較演算子：
<=、>= - 空の山括弧：
<> - 矢印：
<--、--> - ジェネリック型：
Promise<T>、Array<string> - 小なり記号の後のスペース：
< value - 無効な疑似タグ：
<link>、<tag>（有効な HTML ではありません）
トラブルシューティング
サニタイザーを実行してもビルドに失敗する
- Docusaurus のキャッシュをクリアします：
npm run clear - サニタイザーを再実行します：
npm run sanitize:mdx -- --fix - 再ビルドします：
npm run build
誤検出
有効な JSX コンポーネントがエスケープされる場合：
- PascalCase が使われていることを確認します（例：
<MyComponent>） - 有効な HTML5 要素であることを確認します
手動でのエスケープ
例外的なケースでは、ソース内で手動でエスケープします。
- インラインコードにはバッククォートを使います：
`<T>` - 複数行のコードにはフェンス付きコードブロックを使います
- HTML エンティティを使います：
<と>
参考資料
コメント
Markdown 対応