Skip to main content
skill CX Codex

mdx-sanitizer — Claude Code skill: what it does, how to install

mdx-sanitizer escapes angle brackets, TypeScript generics and Liquid templates in MDX before Docusaurus builds. Use it when pre-commit hooks or builds fail on unexpected token.

MIT 202 installs ★ 274 updated 2026-09-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a claude-code
Open on GitHub

What mdx-sanitizer does

The skill detects and fixes patterns that MDX 2.x parses as JSX: unescaped < and > in prose, generics like Promise<T>, comparison operators <= and >=, arrows -->, and pseudo-tags like <link>. It runs at three points: during sync from .claude/skills/ to website/docs/, in a git hook before commit via validate-brackets.js, and at build time in prebuild.

Code inside backticks and fenced blocks is left untouched. Brackets are replaced with HTML entities (&lt;, &gt;) to preserve rendering. Running npm run sanitize:mdx checks files; npm run fix:mdx fixes them in place. No FFmpeg, Python or external APIs required.

What it helps with

  • escape TypeScript generics and comparison operators in MDX before Docusaurus build
  • fix pre-commit hook failures on invalid angle brackets
  • prevent content from being parsed as JSX when Liquid templates are present

Example prompts for the agent

  • Check MDX files in website/docs/ for unclosed brackets and generics.
  • Fix unexpected token < errors in .mdx files under docs/.
  • Run npm run sanitize:mdx -- --fix for all project files.

How to install mdx-sanitizer

1Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a claude-code

2Manually: put the files in place

~/.claude/skills/mdx-sanitizer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mdx-sanitizer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mdx-sanitizer

How to install mdx-sanitizer in Claude Code?

Run npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a claude-code, then open ~/.claude/skills/mdx-sanitizer/SKILL.md.

What does mdx-sanitizer do?

It escapes angle brackets, TypeScript generics, comparison operators and Liquid templates in MDX files so that Docusaurus does not parse them as JSX and fail the build.

When is mdx-sanitizer needed?

When a pre-commit hook or Docusaurus build fails with unexpected token on angle brackets, generics or {{ }} templates.

Source text

SKILL.md · MIT
---
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&lt;T&gt;`, `Array&lt;string&gt;`, `Map&lt;K, V&gt;`
- **Comparisons**: `&lt;100ms`, `&lt;=`, `&gt;=`
- **Arrows**: `--&gt;`, `&lt;--`, `-&gt;`
- **Invalid tags**: `&lt;link&gt;` in prose, `&lt;tag&gt;` placeholders
- **Empty brackets**: `&lt;&gt;`

## 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)
```bash
cd website
npm run sanitize:mdx
# or with verbose output
npm run sanitize:mdx -- --verbose
```

### Fix All Issues
```bash
cd website
npm run sanitize:mdx -- --fix
# or shorthand
npm run fix:mdx
```

### Programmatic API
```typescript
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
}
```

## Escaping Strategies

The sanitizer uses HTML entities for maximum compatibility:

| Pattern | Original | Escaped |
|---------|----------|---------|
| Less-than | `<` | `&lt;` |
| Greater-than | `>` | `&gt;` |
| Generics | `&lt;T&gt;` | `&amp;lt;T&amp;gt;` |
| Comparison | `&lt;=` | `&amp;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**: `&lt;100`, `&lt;0.5ms`
2. **Comparison operators**: `&lt;=`, `&gt;=`
3. **Empty brackets**: `&lt;&gt;`
4. **Arrows**: `&lt;--`, `--&gt;`
5. **Generic types**: `Promise&lt;T&gt;`, `Array&lt;string&gt;`
6. **Space after less-than**: `&lt; value`
7. **Invalid pseudo-tags**: `&lt;link&gt;`, `&lt;tag&gt;` (not valid HTML)

## Troubleshooting

### Build Still Fails After Running Sanitizer

1. Clear Docusaurus cache: `npm run clear`
2. Re-run sanitizer: `npm run sanitize:mdx -- --fix`
3. Rebuild: `npm run build`

### False Positives

If valid JSX components are being escaped:
- Ensure they use PascalCase (e.g., `&lt;MyComponent&gt;`)
- Check they're valid HTML5 elements

### Manual Escaping

For edge cases, manually escape in source:
- Use backticks for inline code: `` `&lt;T&gt;` ``
- Use fenced code blocks for multi-line
- Use HTML entities: `&lt;` and `&gt;`

## Sources

- [MDX Troubleshooting](https://mdxjs.com/docs/troubleshooting-mdx/)
- [TypeDoc MDX Issues](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/167)

© curiositech · MIT · curiositech/some_claude_skills

Similar skills

All skills for DevOps and infrastructure →

From the same set180

The whole set →
research-analyst research-analyst is a Claude Code skill for market research, competitive analysis, and methodology evaluation. It delivers reasoned recommendations with cited sources. CX Codex +1 206installs form-validation-architect The form-validation-architect skill helps design React forms with react-hook-form and Zod. Use it for multi-step flows, dynamic fields, and asynchronous validation. CX Codex +1 205installs llm-streaming-response-handler llm-streaming-response-handler builds production LLM streaming interfaces with Server-Sent Events and live token rendering. Helps add AbortController cancellation and stream error recovery. CX Codex +1 205installs skill-architect skill-architect is a Claude Code skill for designing, auditing, and debugging agent skills. It helps diagnose misactivation and organize expertise into three layers. CX Codex +1 204installs github-actions-pipeline-builder github-actions-pipeline-builder writes GitHub Actions workflows: matrix builds, dependency caching, deployments, automated tests, security scans, release automation. Triggers on "GitHub Actions", "CI/CD", "workflow", "deployment pipeline". CX Codex +1 202installs physics-rendering-expert physics-rendering-expert guides physics implementation for ropes, cables, and cloth using Position-Based Dynamics (PBD) and Verlet integration. Avoids spring instability and Euler gimbal lock. CX Codex +1 201installs supabase-admin supabase-admin — a skill for Supabase database work: schema design, Row Level Security policies, migrations, and query debugging. It helps when an agent modifies the database structure or figures out why a query returns nothing. CX Codex +1 200installs playwright-e2e-tester playwright-e2e-tester is a Claude Code skill that generates Playwright test suites, sets up Page Object models, and configures CI/CD for browser automation. CX Codex +1 200installs

Project sponsors

Companies that keep this analytics open