关于 mdx-sanitizer
用于处理 MDX 内容中可能触发 JSX 解析错误的清理技能，面向维护文档构建流程的开发者。它提供同步时清理、提交前检查和构建时验证，并保护代码块内容。
主要功能
- 01识别冲突的尖括号模式
- 02使用 HTML 实体转义内容
- 03保留代码块与行内代码
- 04提供检查和修复命令
- 05集成提交前及构建验证
适用场景
- 01修正文档中的 TypeScript 泛型文本
- 02避免比较符号导致 MDX 构建失败
- 03检查待提交文档的括号问题
- 04同步技能文档时清理内容
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/mdx-sanitizer确认已加载。
附带文件.claude-plugin/plugin.json
详细介绍
MDX 清理器
全面的 MDX 内容清理器，可防止由尖括号、泛型及其他冲突模式引起的 JSX 解析错误。
问题
MDX 2.x 会将未转义的 < 和 { 视为 JSX 语法。当内容包含以下内容时，会导致构建失败：
- TypeScript 泛型：
Promise<T>、Array<string>、Map<K, V> - 比较运算：
<100ms、<=、>= - 箭头：
-->、<--、-> - 无效标签：正文中的
<link>、占位符<tag> - 空括号：
<>
解决方案架构
此工具采用三层防护：
1. 同步时清理（主动防护）
从 .claude/skills/ 同步到 website/docs/ 时清理内容：
syncSkillDocs.ts- 主要技能文件syncSkillSubpages.ts- 参考文件doc-generator.ts- 生成的文档
2. 提交前验证（响应式防护）
Git 提交前钩子使用 validate-brackets.js 验证文件。
3. 构建时验证（最终检查）
npm run validate:all 会作为 prebuild 的一部分运行，以捕获任何问题。
用法
检查问题（试运行）
cd website
npm run sanitize:mdx
# or with verbose output
npm run sanitize:mdx -- --verbose
修复所有问题
cd website
npm run sanitize:mdx -- --fix
# or shorthand
npm run fix:mdx
程序化 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
}
转义策略
清理器使用 HTML 实体，以实现最高兼容性：
| 模式 | 原始内容 | 转义后 |
|---|---|---|
| 小于号 | < | < |
| 大于号 | > | > |
| 泛型 | <T> | &lt;T&gt; |
| 比较运算 | <= | &lt;= |
代码块（``` 或 `）中的内容会自动受到保护，不会被转义。
修改的文件
website/scripts/lib/mdx-sanitizer.ts- 核心清理器模块website/scripts/sanitize-mdx.ts- CLI 包装器website/scripts/syncSkillDocs.ts- 集成website/scripts/syncSkillSubpages.ts- 集成website/scripts/lib/doc-generator.ts- 集成website/package.json- npm 脚本
检测的模式
- 小于号后接数字：
<100、<0.5ms - 比较运算符：
<=、>= - 空括号：
<> - 箭头：
<--、--> - 泛型：
Promise<T>、Array<string> - 小于号后有空格：
< value - 无效的伪标签：
<link>、<tag>（不是有效的 HTML）
故障排除
运行清理器后构建仍然失败
- 清除 Docusaurus 缓存：
npm run clear - 重新运行清理器：
npm run sanitize:mdx -- --fix - 重新构建：
npm run build
误报
如果有效的 JSX 组件被转义：
- 确保组件使用 PascalCase（例如
<MyComponent>） - 检查它们是否为有效的 HTML5 元素
手动转义
对于边缘情况，可在源文件中手动转义：
- 行内代码使用反引号：
`<T>` - 多行内容使用围栏代码块
- 使用 HTML 实体：
<和>
来源
评论
支持 Markdown