Mdx Sanitizer

MDX Sanitizer

Comprehensive MDX content sanitizer that prevents JSX parsing errors caused by angle brackets, generics, and other conflicting patterns.

Decision Points

When to sanitize vs validate vs wrap:

Content Analysis:
├── Inside code blocks (```, `)
│   └── → Skip sanitization (already protected)
├── Contains TypeScript generics (`Promise<T>`)
│   └── → Sanitize with HTML entities
├── Contains comparisons (`<100ms`, `<=`)
│   └── → Sanitize with HTML entities  
├── Contains arrows (`->`, `<--`)
│   └── → Sanitize with HTML entities
├── Valid JSX components (PascalCase)
│   └── → Skip sanitization (preserve functionality)
├── Valid HTML5 elements (`<div>`, `<span>`)
│   └── → Skip sanitization (preserve functionality)
├── Invalid pseudo-tags (`<link>` in prose)
│   └── → Sanitize with HTML entities
└── Documentation examples
    ├── If showing code syntax → Wrap in code blocks
    └── If showing output/prose → Sanitize with HTML entities

Content type decision matrix:

Failure Modes

Schema Bloat: Over-sanitizing valid JSX

• Detection: Valid React components getting escaped (<Button> instead of <Button>)
• Diagnosis: Sanitizer not recognizing PascalCase or valid HTML5 elements
• Fix: Update whitelist for valid JSX patterns, test with isMdxSafe() first

Escape Cascade: Double-escaping already sanitized content

• Detection: Seeing < instead of < in output
• Diagnosis: Running sanitizer multiple times on same content
• Fix: Check if content already escaped with validateMdxSafety() before processing

Code Block Pollution: Sanitizing content that should stay literal

• Detection: Code examples showing <T> instead of <T>
• Diagnosis: Sanitizer processing content inside code fences
• Fix: Verify code block detection logic, wrap examples properly

Context Blindness: Wrong sanitization strategy for content type

• Detection: Documentation examples breaking or looking wrong
• Diagnosis: Not distinguishing between code syntax vs prose descriptions
• Fix: Analyze context - if showing syntax, use code blocks; if describing, sanitize

Validation Bypass: Files passing validation but failing build

• Detection: npm run validate:all passes but npm run build fails with JSX errors
• Diagnosis: Build-time MDX parsing stricter than validation regex
• Fix: Clear Docusaurus cache, re-run full sanitization, check for edge patterns

Worked Examples

Scenario 1: TypeScript API Documentation

Input content:

The `createMap` function returns `Promise<Map<string, User>>` where each User has...
Performance is <100ms for datasets <=1000 items.

Decision process:

1. Scan for code blocks → None found
2. Identify patterns → Promise<Map<string, User>>, <100ms, <=1000
3. Check if valid JSX → No, these are TypeScript generics and comparisons
4. Apply HTML entity escaping

Output:

The `createMap` function returns `Promise<Map<string, User>>` where each User has...
Performance is <100ms for datasets <=1000 items.

Expert insight: Novice might wrap entire line in code block, losing prose flow. Expert selectively escapes only the problematic characters while preserving readability.

Scenario 2: Component Usage Guide

Input content:

Use <Button variant="primary"> for main actions.
The <link> tag should be avoided in favor of <Link>.

Decision process:

1. Analyze first pattern → <Button variant="primary"> has PascalCase, valid JSX
2. Skip sanitization for Button component
3. Analyze second pattern → <link> in prose context, not valid JSX usage
4. Sanitize invalid tag references

Output:

Use <Button variant="primary"> for main actions.  
The &lt;link&gt; tag should be avoided in favor of <Link>.

Trade-off analysis: Preserving functional JSX while sanitizing prose references maintains both functionality and safety.

Quality Gates

• All < characters outside code blocks are either valid JSX components or HTML-entity escaped
• No < double-escaping patterns in output
• Code blocks (``` and `) preserve original angle brackets
• PascalCase components (<MyComponent>) remain unescaped
• Valid HTML5 elements (<div>, <span>, <a>) remain unescaped
• TypeScript generics (Promise<T>) are escaped to Promise<T>
• Comparison operators (<100, <=) are escaped
• validateMdxSafety() returns no issues for processed content
• npm run build completes without JSX parsing errors
• Visual inspection confirms proper rendering in browser

NOT-FOR Boundaries

This skill is NOT for:

• Dynamic JSX props with runtime values → Use proper JSX escaping libraries like escape-html or React's built-in escaping
• Server-side HTML sanitization → Use DOMPurify or similar XSS protection libraries
• Markdown-to-HTML conversion → Use dedicated parsers like marked or remark
• Syntax highlighting in code blocks → Handled by Prism.js/highlight.js in build pipeline
• User-generated content sanitization → Use isomorphic-dompurify with CSP policies
• Build-time MDX plugin development → Use @mdx-js/mdx plugin API instead

Delegation patterns:

• For XSS protection → xss-security-skill
• For React component escaping → react-escaping-skill
• For build system integration → docusaurus-config-skill
• For regex pattern development → regex-patterns-skill