#!/usr/bin/env node /** * Convert Vocs markdown to Mintlify MDX * * Conversions: * - :::note → * - :::tip → * - :::warning → * - :::info → * - HomePage.Root → CardGroup (for landing page) * - Update internal links (/path → /usuarios/path) * - Validate frontmatter (title, description) * - Check for broken images */ const fs = require('fs'); const path = require('path'); const { glob } = require('glob'); // Configuration const SOURCE_DIR = path.resolve(__dirname, '../../docs/docs/pages'); const TARGET_DIR = path.resolve(__dirname, '../usuarios'); const URL_PREFIX = '/usuarios'; // Statistics const stats = { filesProcessed: 0, errors: [], warnings: [], missingImages: [] }; /** * Convert Vocs admonitions to Mintlify components */ function convertAdmonitions(content) { // :::note Title\nContent\n::: → \nContent\n content = content.replace(/:::note\s+(.*?)\n([\s\S]*?):::/gm, (match, title, body) => { const trimmedTitle = title.trim(); const trimmedBody = body.trim(); if (trimmedTitle) { return `\n${trimmedBody}\n`; } return `\n${trimmedBody}\n`; }); // :::tip → content = content.replace(/:::tip\s+(.*?)\n([\s\S]*?):::/gm, (match, title, body) => { const trimmedTitle = title.trim(); const trimmedBody = body.trim(); if (trimmedTitle) { return `\n${trimmedBody}\n`; } return `\n${trimmedBody}\n`; }); // :::warning → content = content.replace(/:::warning\s+(.*?)\n([\s\S]*?):::/gm, (match, title, body) => { const trimmedTitle = title.trim(); const trimmedBody = body.trim(); if (trimmedTitle) { return `\n${trimmedBody}\n`; } return `\n${trimmedBody}\n`; }); // :::info → content = content.replace(/:::info\s+(.*?)\n([\s\S]*?):::/gm, (match, title, body) => { const trimmedTitle = title.trim(); const trimmedBody = body.trim(); if (trimmedTitle) { return `\n${trimmedBody}\n`; } return `\n${trimmedBody}\n`; }); return content; } /** * Convert HomePage components to Mintlify CardGroup (for landing page only) */ function convertHomePage(content) { if (!content.includes('HomePage.Root')) return content; // This is a simplified conversion for the landing page // We'll create a more manual/polished version in Phase 2 let converted = content; // Remove import statement converted = converted.replace(/import\s+\{.*HomePage.*\}\s+from\s+['"]vocs\/components['"]\s*/g, ''); // Convert HomePage structure to basic Mintlify components converted = converted.replace(/[\s\S]*?<\/HomePage\.Root>/g, (match) => { // Extract description const descMatch = match.match(/([\s\S]*?)<\/HomePage\.Description>/); const description = descMatch ? descMatch[1].trim() : ''; // Extract tagline const taglineMatch = match.match(/([\s\S]*?)<\/HomePage\.Tagline>/); const tagline = taglineMatch ? taglineMatch[1].trim() : ''; // Extract buttons const buttonMatches = [...match.matchAll(/]*>([\s\S]*?)<\/HomePage\.Button>/g)]; let result = '# Bem-vindo ao Nova Gestão\n\n'; if (tagline) { result += `${tagline}\n\n`; } if (description) { result += `${description}\n\n`; } if (buttonMatches.length > 0) { result += '## Começar\n\n\n'; for (const [, href, text] of buttonMatches) { const updatedHref = href.startsWith('/') ? URL_PREFIX + href : href; result += ` \n`; } result += '\n'; } return result; }); return converted; } /** * Update internal links to include /usuarios prefix */ function updateInternalLinks(content) { // Update markdown links: [text](/path) → [text](/usuarios/path) content = content.replace( /\[([^\]]+)\]$(\/[^)]+)$/g, (match, text, url) => { // Don't change image paths or external links if (url.startsWith('/images/') || url.startsWith('http')) { return match; } // Don't add prefix if it already exists if (url.startsWith(URL_PREFIX)) { return match; } // Add /usuarios prefix return `[${text}](${URL_PREFIX}${url})`; } ); return content; } /** * Add or enhance frontmatter */ function ensureFrontmatter(filePath, content) { const relativePath = path.relative(SOURCE_DIR, filePath); // Check if frontmatter exists const hasFrontmatter = content.startsWith('---'); if (hasFrontmatter) { // Frontmatter exists, validate it has title const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/); if (frontmatterMatch) { const frontmatter = frontmatterMatch[1]; if (!frontmatter.includes('title:')) { stats.warnings.push(`${relativePath}: Frontmatter missing title`); } } return content; } // No frontmatter - extract title from first H1 const h1Match = content.match(/^#\s+(.+)$/m); if (!h1Match) { stats.warnings.push(`${relativePath}: No H1 title found, cannot generate frontmatter`); return content; } const title = h1Match[1].trim(); // Add frontmatter at the top const frontmatter = `--- title: ${title} --- `; return frontmatter + content; } /** * Check for referenced images */ function checkImages(filePath, content) { const relativePath = path.relative(SOURCE_DIR, filePath); // Find all image references const imageMatches = content.matchAll(/!\[.*?\]$(.*?)$/g); for (const match of imageMatches) { const imagePath = match[1]; // Skip external images if (imagePath.startsWith('http')) continue; // Check if image exists in source docs const absolutePath = path.resolve(SOURCE_DIR, '..', imagePath.slice(1)); if (!fs.existsSync(absolutePath)) { stats.missingImages.push({ file: relativePath, image: imagePath }); } } } /** * Convert a single file */ function convertFile(sourcePath) { const relativePath = path.relative(SOURCE_DIR, sourcePath); try { let content = fs.readFileSync(sourcePath, 'utf-8'); // Apply conversions content = convertAdmonitions(content); content = convertHomePage(content); content = updateInternalLinks(content); content = ensureFrontmatter(sourcePath, content); // Check for issues checkImages(sourcePath, content); // Determine target path const targetPath = path.join(TARGET_DIR, relativePath); // Create directory if it doesn't exist fs.mkdirSync(path.dirname(targetPath), { recursive: true }); // Write converted content fs.writeFileSync(targetPath, content, 'utf-8'); console.log(`✅ Converted: ${relativePath}`); stats.filesProcessed++; } catch (error) { stats.errors.push({ file: relativePath, error: error.message }); console.error(`❌ Error converting ${relativePath}: ${error.message}`); } } /** * Main execution */ async function main() { console.log('🚀 Starting Vocs → Mintlify conversion\n'); console.log(`Source: ${SOURCE_DIR}`); console.log(`Target: ${TARGET_DIR}\n`); // Find all MDX files const files = await glob(`${SOURCE_DIR}/**/*.mdx`); console.log(`Found ${files.length} files to convert\n`); // Convert each file files.forEach(convertFile); // Print summary console.log('\n' + '='.repeat(60)); console.log('📊 Conversion Summary'); console.log('='.repeat(60)); console.log(`✅ Files processed: ${stats.filesProcessed}`); console.log(`⚠️ Warnings: ${stats.warnings.length}`); console.log(`❌ Errors: ${stats.errors.length}`); console.log(`🖼️ Missing images: ${stats.missingImages.length}`); // Print warnings if (stats.warnings.length > 0) { console.log('\n⚠️ Warnings:'); stats.warnings.forEach(warning => console.log(` - ${warning}`)); } // Print errors if (stats.errors.length > 0) { console.log('\n❌ Errors:'); stats.errors.forEach(({ file, error }) => { console.log(` - ${file}: ${error}`); }); } // Print missing images if (stats.missingImages.length > 0) { console.log('\n🖼️ Missing images:'); stats.missingImages.forEach(({ file, image }) => { console.log(` - ${file} references ${image}`); }); } console.log('\n✨ Conversion complete! Check the output in:'); console.log(` ${TARGET_DIR}/`); // Exit with error code if there were errors if (stats.errors.length > 0) { process.exit(1); } } // Run if called directly if (require.main === module) { main().catch(error => { console.error('Fatal error:', error); process.exit(1); }); } module.exports = { convertFile, convertAdmonitions, convertHomePage, updateInternalLinks };

Field	Type	Description
code required	`ErrorCodeEnum`!	Error classification code
details	`JSON`	Additional error context
message required	`String`!	Human-readable error message
path required	[`String`!]	GraphQL path where error occurred

Começar

Guias

Importações

Referência da API

Changelog

​Error

​Fields

​Related Types

ErrorCodeEnum

Error

Fields

Related Types