#!/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

Building Blocks of LLM Apps

Tips Tricks and Resources

Introduction to LCEL

Adding Memory to LLM Apps

Performing Retrieval

Implementing Chains

Using Tools

Building Agents

Conclusion

Interacting with LL Ms

Key Components of Lang Chain

Overview of Lang Chain

Page Not Found