/** * AST-based Markdown → MDX-safe Converter for Mintlify * * TL;DR: Парсим Markdown в AST, нормализуем опасные узлы, генерируем MDX-safe output. * Никаких regex — только AST-трансформации. * * Usage: * node scripts/md-to-mdx.js [input-dir] [output-dir] * node scripts/md-to-mdx.js docs-src docs */ import { unified } from 'unified'; import remarkParse from 'remark-parse'; import remarkStringify from 'remark-stringify'; import { visit } from 'unist-util-visit'; import fs from 'fs/promises'; import path from 'path'; // ============================================================================ // DANGEROUS PATTERNS (что ломает Mintlify/Acorn) // ============================================================================ const PATTERNS = { // JSON-like: { "key": "value" } или { key: value } jsonLike: /\{[^}]*[":][^}]*\}/, // Curly braces в любом контексте: {something} curlyBraces: /\{[^}]+\}/g, // Angle brackets (ложный JSX): или < 10 angleBrackets: /<[^>]+>|<\s*\d+|>\s*\d+/g, // HTML tags htmlTags: /<\/?(?:div|span|br|p|a|img|table|tr|td|th|ul|ol|li|h[1-6]|strong|em|code|pre|blockquote)[^>]*>/gi, // Arrow functions и JS patterns jsPatterns: /=>\s*[{(]|\.map\(|\.filter\(|\.reduce\(|function\s*\(/g, // SQL-like patterns вне code block sqlPatterns: /(?:SELECT|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER)\s+/i, // HTTP methods httpPatterns: /(?:GET|POST|PUT|DELETE|PATCH)\s+\/[^\s]*/, }; // ============================================================================ // AST TRANSFORMER PLUGIN // ============================================================================ function remarkMdxSafe() { return (tree) => { // Проход по всем узлам дерева visit(tree, (node, index, parent) => { // 1. Обработка текстовых узлов if (node.type === 'text') { node.value = sanitizeText(node.value); } // 2. Обработка inline code — оставляем как есть if (node.type === 'inlineCode') { return; } // 3. Обработка code blocks — оставляем как есть if (node.type === 'code') { return; } // 4. Обработка HTML узлов if (node.type === 'html') { // Конвертируем HTML в code block или удаляем const sanitized = sanitizeHtml(node.value); if (sanitized) { node.type = 'code'; node.lang = 'html'; node.value = sanitized; } else { // Удаляем узел if (parent && typeof index === 'number') { parent.children.splice(index, 1); return index; // Возвращаемся к тому же индексу } } } // 5. Обработка параграфов — проверяем на опасные паттерны if (node.type === 'paragraph') { const text = extractText(node); // Если весь параграф — это JSON/SQL/HTTP, оборачиваем в code block if (shouldBeCodeBlock(text)) { const codeNode = { type: 'code', lang: detectLanguage(text), value: text, }; if (parent && typeof index === 'number') { parent.children[index] = codeNode; } } } }); }; } // ============================================================================ // SANITIZATION FUNCTIONS // ============================================================================ /** * Экранирует опасные символы в тексте */ function sanitizeText(text) { let result = text; // Экранируем { } если они не в code result = result.replace(/\{/g, '\\{'); result = result.replace(/\}/g, '\\}'); // Экранируем < > если они похожи на JSX result = result.replace(/<(?=[A-Z])/g, '\\<'); result = result.replace(/<(?=\/[A-Z])/g, '\\<'); return result; } /** * Обрабатывает HTML — возвращает null если нужно удалить */ function sanitizeHtml(html) { // Простые теги типа
удаляем if (/^$/i.test(html.trim())) { return null; } // Остальной HTML возвращаем для code block return html; } /** * Извлекает текст из узла с детьми */ function extractText(node) { if (node.value) return node.value; if (node.children) { return node.children.map(extractText).join(''); } return ''; } /** * Определяет, должен ли текст быть в code block */ function shouldBeCodeBlock(text) { const trimmed = text.trim(); // JSON-like структуры if (trimmed.startsWith('{') && trimmed.endsWith('}')) { return true; } // SQL queries if (PATTERNS.sqlPatterns.test(trimmed)) { return true; } // HTTP requests if (PATTERNS.httpPatterns.test(trimmed)) { return true; } // JS patterns if (PATTERNS.jsPatterns.test(trimmed)) { return true; } return false; } /** * Определяет язык для code block */ function detectLanguage(text) { const trimmed = text.trim(); if (trimmed.startsWith('{') || trimmed.startsWith('[')) { return 'json'; } if (PATTERNS.sqlPatterns.test(trimmed)) { return 'sql'; } if (PATTERNS.httpPatterns.test(trimmed)) { return 'http'; } if (PATTERNS.jsPatterns.test(trimmed)) { return 'javascript'; } return 'text'; } // ============================================================================ // FILE PROCESSING // ============================================================================ /** * Конвертирует один файл Markdown → MDX-safe */ async function convertFile(inputPath, outputPath) { const content = await fs.readFile(inputPath, 'utf-8'); // Извлекаем frontmatter (если есть) const { frontmatter, body } = extractFrontmatter(content); // Процессим через unified pipeline const result = await unified() .use(remarkParse) .use(remarkMdxSafe) .use(remarkStringify, { bullet: '-', emphasis: '*', strong: '**', fence: '`', fences: true, }) .process(body); // Собираем результат let output = ''; if (frontmatter) { output += `---\n${frontmatter}\n---\n\n`; } output += String(result); // Создаём директорию если нужно await fs.mkdir(path.dirname(outputPath), { recursive: true }); // Записываем результат await fs.writeFile(outputPath, output, 'utf-8'); console.log(`✓ ${inputPath} → ${outputPath}`); } /** * Извлекает frontmatter из файла */ function extractFrontmatter(content) { const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/); if (match) { return { frontmatter: match[1], body: match[2], }; } return { frontmatter: null, body: content, }; } /** * Рекурсивно обрабатывает директорию */ async function processDirectory(inputDir, outputDir) { const entries = await fs.readdir(inputDir, { withFileTypes: true }); for (const entry of entries) { const inputPath = path.join(inputDir, entry.name); if (entry.isDirectory()) { const outputSubDir = path.join(outputDir, entry.name); await processDirectory(inputPath, outputSubDir); } else if (entry.name.endsWith('.md')) { const outputPath = path.join( outputDir, entry.name.replace(/\.md$/, '.mdx') ); await convertFile(inputPath, outputPath); } } } // ============================================================================ // CLI // ============================================================================ async function main() { const args = process.argv.slice(2); const inputDir = args[0] || 'docs-src'; const outputDir = args[1] || 'docs'; console.log(`\n🔄 MD → MDX-safe Converter`); console.log(` Input: ${inputDir}`); console.log(` Output: ${outputDir}\n`); try { const stat = await fs.stat(inputDir); if (stat.isDirectory()) { await processDirectory(inputDir, outputDir); } else { // Один файл const outputPath = outputDir.endsWith('.mdx') ? outputDir : inputDir.replace(/\.md$/, '.mdx'); await convertFile(inputDir, outputPath); } console.log(`\n✅ Done! MDX-safe files ready in ${outputDir}/\n`); } catch (err) { console.error(`\n❌ Error: ${err.message}\n`); process.exit(1); } } main();

Getting started

Customization

Writing content

AI tools

Page Not Found