К основному содержанию
скилл CX Codex

mdx-sanitizer — скилл для Claude Code: что делает и как установить

Скилл mdx-sanitizer для Claude Code экранирует в MDX конструкции, которые MDX 2.x принимает за JSX, перед сборкой Docusaurus. Исправляет ошибки unexpected token в прекоммит-хуках и билде.

MIT 202 установок ★ 274 обновлён 2026-09-06

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a claude-code
Открыть на GitHub

Что делает mdx-sanitizer

Скилл находит и исправляет конструкции, которые MDX 2.x принимает за JSX: неэкранированные < и > в тексте, дженерики вроде Promise<T>, операторы сравнения <= и >=, стрелки --> и псевдотеги <link>. Работает в трёх точках: при синхронизации из .claude/skills/ в website/docs/, в git-хуке перед коммитом через validate-brackets.js и на этапе билда в prebuild.

Внутри код в обратных кавычках и фенсированные блоки не трогает. Заменяет скобки на HTML-сущности (&lt;, &gt;), чтобы не сломать рендеринг. Запуск npm run sanitize:mdx проверяет файлы, npm run fix:mdx исправляет на месте. Без FFmpeg, Python или внешних API.

Какие задачи решает

  • экранировать дженерики TypeScript и операторы сравнения в MDX перед билдом Docusaurus
  • зафиксить падения прекоммит-хука на невалидных угловых скобках
  • защитить контент от парсинга как JSX при наличии шаблонов Liquid

Примеры запросов агенту

  • Проверь MDX-файлы в website/docs/ на незакрытые скобки и дженерики.
  • Исправь ошибки unexpected token < в файлах .mdx каталога docs/.
  • Запусти npm run sanitize:mdx -- --fix для всех файлов проекта.

Как установить mdx-sanitizer

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/mdx-sanitizer/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о mdx-sanitizer

Как установить mdx-sanitizer в Claude Code?

Выполни npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a claude-code, затем открой ~/.claude/skills/mdx-sanitizer/SKILL.md.

Что делает mdx-sanitizer?

Экранирует угловые скобки, дженерики TypeScript, операторы сравнения и шаблоны Liquid в MDX-файлах, чтобы Docusaurus не принял их за JSX и не упал при билде.

Когда mdx-sanitizer нужен?

Когда прекоммит-хук или билд Docusaurus падает с ошибкой unexpected token на угловых скобках, дженериках или шаблонах {{ }}.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «DevOps и инфраструктура» →
markdown-mdx-content-pipeline-wasp-drone Legion Code Inc. Субагент markdown-mdx-content-pipeline-wasp-drone для Claude Code и Codex собирает и проверяет Markdown/MDX-пайплайны от исходников до HTML, JSX или React. Настраивает компиляторы, плагины, подсветку, формулы, диаграммы и очистку HTML. CX Codex ★ 96звёзд репо docusaurus-expert davila7 Субагент docusaurus-expert для Claude Code настраивает сайты Docusaurus v2 и v3: структуру, боковое меню и MDX-статьи, а также исправляет сбои сборки. CX Codex 1 143установок user-manual-generator Mharbulous Скилл user-manual-generator для Claude Code генерирует пользовательскую документацию и статический сайт по исходному коду проекта. Помогает подготовить инструкции для конечных пользователей. CX Codex +1 2установок blog-rewrite AgriciDaniel Скилл blog-rewrite анализирует и переписывает статьи блога под критерии Google SEO и видимость в ответах ИИ-ассистентов с проверкой первоисточников. CX Codex +1 2 700установок blog-write AgriciDaniel Скилл blog-write пишет новую статью для блога по теме, брифу или плану. Настроен на двойную оптимизацию — попадание в Google и цитирование ИИ-ассистентами, не трогает существующие посты. CX Codex +1 2 700установок docs-write metabase Скилл docs-write помогает писать и редактировать Markdown и MDX в стиле Metabase. Он пригодится для рабочих инструкций, описаний функций и другой документации. CX Codex +1 2 100установок

Из того же набора180

Весь набор →
research-analyst Скилл research-analyst для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode — проводит исследование рынка, конкурентный анализ и оценку методологий. Выдаёт рекомендации с обоснованием и цитатами источников. CX Codex +1 206установок form-validation-architect Скилл form-validation-architect для Claude Code проектирует React-формы с проверкой через react-hook-form и Zod. Описывает многошаговые сценарии, динамические поля и асинхронную валидацию. CX Codex +1 205установок llm-streaming-response-handler Скилл llm-streaming-response-handler настраивает потоковый вывод токенов через Server-Sent Events в интерфейсах чатов. Помогает добавить прерывание генерации, курсор набора текста и обработку сбоев сети. CX Codex +1 205установок skill-architect Скилл skill-architect для Claude Code создаёт и проверяет Claude Agent Skills. Настраивает их активацию и структуру с прогрессивным раскрытием. CX Codex +1 204установок github-actions-pipeline-builder Скилл github-actions-pipeline-builder собирает CI/CD-пайплайны на GitHub Actions: матричные сборки, кэширование, деплой, тесты, проверки безопасности. Активируется по словам «GitHub Actions», «CI/CD», «workflow», «deployment pipeline». CX Codex +1 202установок physics-rendering-expert Скилл physics-rendering-expert настраивает симуляцию верёвок, кабелей и тканей через Position-Based Dynamics (PBD) и интеграцию Верле. Он предотвращает ошибки с пружинами и углами Эйлера. CX Codex +1 201установок supabase-admin Скилл supabase-admin для Claude Code администрирует Supabase: проектирует схемы, настраивает политики RLS и миграции, отлаживает запросы. Помогает менять структуру базы и выяснять причины пустой выборки. CX Codex +1 200установок playwright-e2e-tester Скилл playwright-e2e-tester помогает писать E2E-тесты на Playwright, настраивать Page Object Model и готовить пайплайны GitHub Actions. Пригодится при автоматизации веб-тестов и отлове регрессий интерфейса. CX Codex +1 200установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой