mdx-sanitizer

name	mdx-sanitizer
description	Sanitize MDX content for Docusaurus builds. Fixes unescaped angle brackets (<, >, &lt;=, &gt;=), Liquid/Nunjucks template syntax ({{ }}), TypeScript generics (Promise&lt;T&gt;), and inline code backtick edge cases. Use when pre-commit hooks fail on bracket or Liquid validation, or when MDX/JSX build errors reference unexpected tokens. NOT for general markdown linting or prose editing.
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep"]
version	1.0.0
triggers	["mdx error","angle bracket","jsx parsing","build failure mdx","escape angle brackets","sanitize markdown"]
metadata	{"category":"DevOps & Automation","tags":["mdx","docusaurus","markdown","build-tools","sanitization"],"pairs-with":[{"skill":"site-reliability-engineer","reason":"MDX build failures are a primary Docusaurus deployment blocker that SRE validates"},{"skill":"technical-writer","reason":"Technical writers produce the MDX content that needs sanitization for safe rendering"},{"skill":"skill-documentarian","reason":"Skill documentation in MDX format requires sanitization before website deployment"}]}

MDX Sanitizer

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

The Problem

MDX 2.x treats unescaped < and { as JSX syntax. This causes build failures when content contains:

• TypeScript generics: Promise<T>, Array<string>, Map<K, V>
• Comparisons: <100ms, <=, >=
• Arrows: -->, <--, ->
• Invalid tags: <link> in prose, <tag> placeholders
• Empty brackets: <>

Solution Architecture

This skill implements a three-layer defense:

1. Sync-Time Sanitization (Proactive)

Content is sanitized when syncing from .claude/skills/ to website/docs/:

• syncSkillDocs.ts - Main skill files
• syncSkillSubpages.ts - Reference files
• doc-generator.ts - Generated docs

2. Pre-Commit Validation (Reactive)

The git pre-commit hook validates files before commit using validate-brackets.js.

3. Build-Time Validation (Final Check)

npm run validate:all runs as part of prebuild to catch any issues.

Usage

Check for Issues (Dry Run)

cd website
npm run sanitize:mdx
# or with verbose output
npm run sanitize:mdx -- --verbose

Fix All Issues

cd website
npm run sanitize:mdx -- --fix
# or shorthand
npm run fix:mdx

Programmatic API

import { sanitizeForMdx, validateMdxSafety, isMdxSafe } from './lib/mdx-sanitizer';


 result = (content, { :  });
 (result.) {
  .();
  fs.(path, result.);
}


 issues = (content, );


 (!(content)) {
  
}