Agent skill · software engineering · erichowens
mdx-sanitizer
Sanitize MDX content for Docusaurus builds. Fixes unescaped angle brackets (<, >, <=, >=), Liquid/Nunjucks template syntax ({{ }}), TypeScript generics (Promise<T>), 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.
Why this skill is useful
Adds executable scripts for sanitizing MDX content that prevent build failures in Docusaurus, which the AI wouldn't generate on its own.
What it needs
Requires npm installed locally. About 3k tokens when loaded. Last updated 2026-07-14. 180 stars on the source repository.
What this skill does
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) Fix All Issues Programmatic API Escaping Strategies The sanitizer uses HTML entities for maximum compatibility: Pattern Original Escaped --------- ---------- --------- Less-than < < Greater-than > > Generics <T> &lt;T&gt; Comparison <= &lt;= Content inside code blocks ( or ) is automatically protected and never escaped. Files Modified website/scripts/lib/mdx-sanitizer.ts - Core sanitizer module website/scripts/sanitize-mdx.ts - CLI wrapper website/scripts/syncSkillDocs.ts - Integration website/scripts/syncSkillSubpages.ts - Integration website/scripts/lib/doc-generator.ts - Integration website/package.json - npm scripts Patterns Detected 1. Less-than before digit: <100, <0.5ms 2. Comparison operators: <=, >= 3. Empty brackets: <> 4. Arrows: <--, --> 5. Generic types: Promise<T>, Array<string> 6. Space after less-than: < value 7. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills erichowens/mdx-sanitizer