About

Imported from curiositech/some_claude_skills (.claude/skills/mdx-sanitizer/SKILL.md). Install upstream with npx skills add curiositech/some_claude_skills --skill mdx-sanitizer. Copyright stays with the author.

MDX Sanitizer

Name: mdx-sanitizer
Author: curiositech

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';

// 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	`<`	`<`
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

Less-than before digit: <100, <0.5ms
Comparison operators: <=, >=
Empty brackets: <>
Arrows: <--, -->
Generic types: Promise<T>, Array<string>
Space after less-than: < value
Invalid pseudo-tags: <link>, <tag> (not valid HTML)

Troubleshooting

Build Still Fails After Running Sanitizer

Clear Docusaurus cache: npm run clear
Re-run sanitizer: npm run sanitize:mdx -- --fix
Rebuild: npm run build

False Positives

If valid JSX components are being escaped:

Ensure they use PascalCase (e.g., <MyComponent>)
Check they're valid HTML5 elements

Manual Escaping

For edge cases, manually escape in source:

Use backticks for inline code: `<T>`
Use fenced code blocks for multi-line
Use HTML entities: < and >

Sources

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/curiositech-some-claude-skills-mdx-sanitizer/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

curiositech-some-claude-skills-mdx-sanitizer.ocm.jsonjson

{
  "ocm": "1",
  "id": "curiositech-some-claude-skills-mdx-sanitizer",
  "kind": "skill",
  "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.",
  "publisher": "curiositech",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "mdx",
      "docusaurus",
      "markdown",
      "build-tools",
      "sanitization",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "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."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/curiositech/some_claude_skills",
      "path": ".claude/skills/mdx-sanitizer/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/curiositech/some_claude_skills/blob/HEAD/.claude/skills/mdx-sanitizer/SKILL.md",
      "key": "curiositech/some_claude_skills/.claude/skills/mdx-sanitizer/SKILL.md"
    },
    "allowed_tools": [
      "Read",
      "Write",
      "Edit",
      "Bash",
      "Glob",
      "Grep"
    ]
  },
  "instructions": "# MDX Sanitizer\n\nComprehensive MDX content sanitizer that prevents JSX parsing errors caused by angle brackets, generics, and other conflicting patterns.\n\n## The Problem\n\nMDX 2.x treats unescaped `<` and `{` as JSX syntax. This causes build failures when content contains:\n\n- **TypeScript generics**: `Promise&lt;T&gt;`, `Array&lt;string&gt;`, `Map&lt;K, V&gt;`\n- **Comparisons**: `&lt;100ms`, `&lt;=`, `&gt;=`\n- **Arrows**: `--&gt;`, `&lt;--`, `-&gt;`\n- **Invalid tags**: `&lt;link&gt;` in prose, `&lt;tag&gt;` placeholders\n- **Empty brackets**: `&lt;&gt;`\n\n## Solution Architecture\n\nThis skill impl",
  "cost": {
    "context_tokens": 918
  }
}

Fetch it by URL: GET /api/v1/registry/curiositech-some-claude-skills-mdx-sanitizer/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.