#!/usr/bin/env node /** * Mintlify MDX Converter * * Converts MDX/MD files to Mintlify-compatible format by: * - Converting nested frontmatter (nextjs.metadata) to flat YAML * - Replacing template syntax ({% %}) with JSX components * - Wrapping images in components * - Removing custom metadata properties * * Usage: node utils/mintlify-converter.js [directory] * Example: node utils/mintlify-converter.js docs/12-Factor-App */ const fs = require('fs'); const path = require('path'); class MintlifyConverter { constructor() { this.stats = { filesProcessed: 0, filesFixed: 0, errors: [] }; } /** * Main conversion function - processes a single file * @param {string} filePath - Path to the MDX/MD file * @returns {object} - { success: boolean, changed: boolean, error?: string } */ convertFile(filePath) { try { const content = fs.readFileSync(filePath, 'utf8'); const originalContent = content; let convertedContent = content; // Step 1: Fix frontmatter - handles nested nextjs.metadata convertedContent = this.fixFrontmatter(convertedContent); // Step 2: Replace template syntax with JSX components convertedContent = this.fixCalloutSyntax(convertedContent); convertedContent = this.fixQuickLinksSyntax(convertedContent); convertedContent = this.fixGenericTemplateTags(convertedContent); // Step 3: Wrap images in Frame components convertedContent = this.wrapImagesInFrame(convertedContent); // Check if changes were made const hasChanges = convertedContent !== originalContent; if (hasChanges) { fs.writeFileSync(filePath, convertedContent, 'utf8'); this.stats.filesFixed++; return { success: true, changed: true }; } return { success: true, changed: false }; } catch (error) { this.stats.errors.push({ file: filePath, error: error.message }); return { success: false, error: error.message }; } } /** * Fix frontmatter: Convert nested nextjs.metadata to flat YAML * Handles both simple and complex nested structures * @param {string} content - File content * @returns {string} - Content with fixed frontmatter */ fixFrontmatter(content) { // Match frontmatter delimiters const frontmatterRegex = /^---\n([\s\S]*?)\n---\n/; const match = content.match(frontmatterRegex); if (!match) return content; let frontmatter = match[1]; const originalFrontmatter = frontmatter; // Check if it has nested nextjs.metadata or any nested structure if (frontmatter.includes('nextjs:') || /^\s*\w+:\s*$/.test(frontmatter)) { // Extract title from root or nested level let title = frontmatter.match(/^\s*title:\s*(.+?)$/m)?.[1] || frontmatter.match(/title:\s*(.+?)$/m)?.[1] || 'Untitled'; title = title.trim().replace(/['"]/g, ''); // Extract description - look in metadata or root level let description = frontmatter.match(/description:\s*(.+?)$/m)?.[1] || ''; description = description.trim().replace(/['"]/g, ''); // Remove any language, locale, or other non-standard properties // Create clean flat frontmatter with only title and description const flatFrontmatter = `--- title: "${title}" description: "${description.replace(/"/g, '\\"')}" --- `; // Only update if the structure actually changed if (frontmatter !== originalFrontmatter || frontmatter.includes('nextjs:')) { return content.replace(frontmatterRegex, flatFrontmatter); } } // Ensure title and description are quoted (even in flat YAML) let updated = false; if (frontmatter.includes('title:') && !frontmatter.match(/title:\s*["']/)) { frontmatter = frontmatter.replace(/title:\s*(.+?)$/m, (match, title) => { const trimmed = title.trim(); return `title: "${trimmed.replace(/"/g, '\\"')}"`; }); updated = true; } if (frontmatter.includes('description:') && !frontmatter.match(/description:\s*["']/)) { frontmatter = frontmatter.replace(/description:\s*(.+?)$/m, (match, desc) => { const trimmed = desc.trim(); return `description: "${trimmed.replace(/"/g, '\\"')}"`; }); updated = true; } if (updated) { return content.replace(frontmatterRegex, `---\n${frontmatter}\n---\n`); } return content; } /** * Convert {% callout %} template syntax to JSX component * Supports various callout types (note, warning, tip, success) * @param {string} content - File content * @returns {string} - Content with converted callouts */ fixCalloutSyntax(content) { // Match: {% callout type="note" title="..." %} ... {% /callout %} const calloutRegex = /\{%\s*callout\s+(?:type=["\']([^"']+)["\']|[^}]*?type=["\']([^"']+)["\'])[^}]*?\s*%\}([\s\S]*?)\{%\s*\/callout\s*%\}/g; return content.replace(calloutRegex, (match, type1, type2, innerContent) => { const type = type1 || type2 || 'note'; const cleanContent = innerContent.trim(); // Map callout types to appropriate icons and colors let icon = 'lightbulb'; let color = '#1CB2FE'; switch (type.toLowerCase()) { case 'warning': case 'warn': icon = 'triangle-alert'; color = '#FF6B6B'; break; case 'tip': icon = 'lightbulb'; color = '#1CB2FE'; break; case 'success': case 'check': icon = 'check-circle'; color = '#51CF66'; break; case 'info': case 'information': icon = 'info'; color = '#4C6EF5'; break; case 'note': default: icon = 'lightbulb'; color = '#1CB2FE'; } return `\n${cleanContent}\n`; }); } /** * Convert {% quick-links %} template syntax to JSX * Parses quick-link attributes and converts to Card components * @param {string} content - File content * @returns {string} - Content with converted card groups */ fixQuickLinksSyntax(content) { // Match: {% quick-links %} ... {% quick-link ... %} ... {% /quick-links %} const quickLinksRegex = /\{%\s*quick-links\s*%\}([\s\S]*?)\{%\s*\/quick-links\s*%\}/g; return content.replace(quickLinksRegex, (match, innerContent) => { // Extract individual quick-link elements const linkRegex = /\{%\s*quick-link\s+([^%}]+)\s*\/%\}/g; const cards = []; let linkMatch; while ((linkMatch = linkRegex.exec(innerContent)) !== null) { const attrs = linkMatch[1]; // Parse attributes from template syntax const titleMatch = attrs.match(/title=["\']([^"']+)["\']/); const iconMatch = attrs.match(/icon=["\']([^"']+)["\']/); const hrefMatch = attrs.match(/href=["\']([^"']+)["\']/); if (titleMatch && hrefMatch) { const title = titleMatch[1]; const href = hrefMatch[1]; const icon = iconMatch ? iconMatch[1] : 'link'; // Map template icons to Mintlify Card icons const iconMap = { 'plugins': 'video', 'link': 'external-link', 'book': 'book', 'code': 'code-2', 'video': 'video', 'play': 'play' }; const cardIcon = iconMap[icon] || icon; cards.push(``); } } if (cards.length === 0) { return match; // Return unchanged if no cards found } return `\n${cards.map(c => c).join('\n')}\n`; }); } /** * Remove any remaining generic template tags that weren't caught by specific handlers * @param {string} content - File content * @returns {string} - Content with removed template tags */ fixGenericTemplateTags(content) { // Remove any remaining {% ... %} tags that aren't part of markdown const remainingTagsRegex = /\{%\s*([a-zA-Z\-]+)(?:[^}]*)%\}/g; return content.replace(remainingTagsRegex, ''); } /** * Wrap raw markdown images in components * Only wraps images that aren't already inside another component * @param {string} content - File content * @returns {string} - Content with wrapped images */ wrapImagesInFrame(content) { // Split content into lines to check context const lines = content.split('\n'); const result = []; let i = 0; while (i < lines.length) { const line = lines[i]; // Check if line is a markdown image and not already wrapped if (/^\s*!\[/.test(line) && !this.isImageWrapped(lines, i)) { result.push(''); result.push(line); result.push(''); } else { result.push(line); } i++; } return result.join('\n'); } /** * Check if an image is already wrapped in a component * Looks at surrounding lines for component tags * @param {array} lines - Array of content lines * @param {number} imageLineIndex - Index of the image line * @returns {boolean} - True if image is already wrapped */ isImageWrapped(lines, imageLineIndex) { // Check previous line for opening tags if (imageLineIndex > 0) { const prevLine = lines[imageLineIndex - 1].trim(); if (prevLine.startsWith(' { const entries = fs.readdirSync(currentPath, { withFileTypes: true }); for (const entry of entries) { const fullPath = path.join(currentPath, entry.name); if (entry.isDirectory()) { traverse(fullPath); } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))) { files.push(fullPath); } } }; traverse(dirPath); return files; } /** * Process all files in a directory recursively * @param {string} dirPath - Directory path * @returns {object} - Statistics object with counts */ processDirectory(dirPath) { const files = this.findMDXFiles(dirPath); console.log(`\nFound ${files.length} .md/.mdx files in ${dirPath}\n`); for (const file of files) { const result = this.convertFile(file); const relPath = path.relative(dirPath, file); if (result.success) { if (result.changed) { console.log(`✅ FIXED: ${relPath}`); } else { console.log(`⏭️ SKIP: ${relPath} (already compatible)`); } } else { console.log(`❌ ERROR: ${relPath} - ${result.error}`); } this.stats.filesProcessed++; } return this.stats; } /** * Print conversion statistics to console */ printStats() { console.log(`\n${'='.repeat(60)}`); console.log('CONVERSION SUMMARY'); console.log(`${'='.repeat(60)}\n`); console.log(`Files Processed: ${this.stats.filesProcessed}`); console.log(`Files Fixed: ${this.stats.filesFixed}`); console.log(`Files Already Compatible: ${this.stats.filesProcessed - this.stats.filesFixed}`); if (this.stats.errors.length > 0) { console.log(`\nErrors: ${this.stats.errors.length}`); this.stats.errors.forEach(err => { console.log(` ❌ ${err.file}: ${err.error}`); }); } console.log(`\n${'='.repeat(60)}\n`); } } // CLI Entry point if (require.main === module) { const args = process.argv.slice(2); const targetDir = args[0] || '/Users/kavyasoni/Development/kodekloud-docs/docs/12-Factor-App'; if (!fs.existsSync(targetDir)) { console.error(`Error: Directory not found: ${targetDir}`); process.exit(1); } const converter = new MintlifyConverter(); converter.processDirectory(targetDir); converter.printStats(); } module.exports = MintlifyConverter;

Introduction

Spacelift Basics

Conclusion

Page Not Found