#!/usr/bin/env node /** * Script to extract div overview content from OpenAPI YAML files * and generate MDX documentation pages. * * This script: * 1. Reads all YAML files in the openapi/ directory * 2. Extracts

content from the description field * 3. Converts HTML to clean MDX format * 4. Generates overview MDX files in api-overviews/ * 5. Updates docs.json to include overview pages in navigation */ const fs = require('fs'); const path = require('path'); const yaml = require('yaml'); const OPENAPI_DIR = path.join(__dirname, '..', 'openapi'); const OUTPUT_DIR = path.join(__dirname, '..', 'api-overviews'); const DOCS_JSON_PATH = path.join(__dirname, '..', 'docs.json'); /** * Convert ALL CAPS or UPPER_CASE text to Title Case */ function toTitleCase(str) { // Replace underscores with spaces let text = str.replace(/_/g, ' '); // Convert to title case (also handle words after &) text = text.toLowerCase().replace(/(?:^|\s|&\s*)\S/g, char => char.toUpperCase()); // Handle special cases and acronyms const specialCases = { 'Api': 'API', 'B2b': 'B2B', 'Graphql': 'GraphQL', 'Sla': 'SLA', 'Slas': 'SLAs', 'Url': 'URL', 'Id': 'ID', 'Oauth': 'OAuth', 'App': 'App', 'And': 'and', 'Or': 'or', 'The': 'the', 'For': 'for', 'Of': 'of', 'In': 'in', 'To': 'to', 'With': 'with', }; // Apply special cases (but keep first word capitalized) const words = text.split(' '); for (let i = 0; i < words.length; i++) { if (specialCases[words[i]]) { // Keep first word capitalized even if it's a lowercase word if (i === 0 && ['and', 'or', 'the', 'for', 'of', 'in', 'to', 'with'].includes(specialCases[words[i]])) { words[i] = words[i]; // Keep as-is (already title cased) } else { words[i] = specialCases[words[i]]; } } } return words.join(' '); } /** * Decode HTML entities */ function decodeHtmlEntities(str) { return str .replace(/&/g, '&') .replace(/</g, '<') .replace(/>/g, '>') .replace(/"/g, '"') .replace(/'/g, "'") .replace(/ /g, ' '); } /** * Check if string is mostly uppercase (ignoring special chars) */ function isMostlyUpperCase(str) { const letters = str.replace(/[^a-zA-Z]/g, ''); if (letters.length === 0) return false; const upperCount = (letters.match(/[A-Z]/g) || []).length; return upperCount / letters.length > 0.8; } /** * Convert HTML content to MDX-friendly markdown */ function htmlToMdx(html) { let content = html; // Extract the h2 title const h2Match = content.match(/

(.*?)<\/h2>/i); let title = h2Match ? decodeHtmlEntities(h2Match[1].trim()) : ''; // Convert ALL CAPS title to Title Case if (title && isMostlyUpperCase(title)) { title = toTitleCase(title); } // Remove the h2 since we'll use frontmatter title content = content.replace(/

.*?<\/h2>/gi, ''); // Convert to bold (ensure space before if needed) content = content.replace(/(\S)/gi, '$1 **'); content = content.replace(/(.?)<\/strong>/gi, '$1'); // Convert to italic* content = content.replace(/(.?)<\/em>/gi, '$1'); // Convert text to [text](...) content = content.replace(/]>(.?)<\/a>/gi, '[$2]($1)'); // Convert to `code` content = content.replace(/(.?)<\/code>/gi, '`$1`'); // Convert tags to paragraphs with proper spacing content = content.replace(/ /gi, '\n\n'); content = content.replace(/<\/p>/gi, ''); // Convert tags to newlines content = content.replace(//gi, '\n'); // Convert and to markdown lists content = content.replace(//gi, '\n'); content = content.replace(/<\/ul>/gi, '\n'); content = content.replace(//gi, '\n- '); content = content.replace(/<\/li>/gi, ''); // Convert to numbered list (simplified) content = content.replace(//gi, '\n'); content = content.replace(/<\/ol>/gi, '\n'); // Remove any remaining HTML tags content = content.replace(/<[^>]+>/g, ''); // Clean up whitespace content = content .split('\n') .map(line => line.trim()) .join('\n') .replace(/\n{3,}/g, '\n\n') .trim(); return { title, content }; } /** * Extract div overview content from YAML file / function extractOverview(yamlContent) { try { const doc = yaml.parse(yamlContent); const description = doc?.info?.description; if (!description) { return null; } // Look for div with id starting with "overview_" const divMatch = description.match(/]>([\s\S]*?)<\/div>/i); if (!divMatch) { return null; } const divId = divMatch[1]; const divContent = divMatch[2]; const apiTitle = doc?.info?.title || ''; return { divId, divContent, apiTitle }; } catch (error) { console.error('Error parsing YAML:', error.message); return null; } } /** * Generate MDX file content / function generateMdx(overview, filename) { const { title, content } = htmlToMdx(overview.divContent); // Create a nice description from the first paragraph const firstParagraph = content.split('\n\n')[0] || ''; const description = firstParagraph .replace(/\\*/g, '') .replace(/\[([^\]]+)\]$[^)]+$/g, '$1') .substring(0, 150) .trim(); const mdx = `--- title: "${title || overview.apiTitle} Overview" description: "${description}" --- # ${title || overview.apiTitle} ${content} `; return mdx; } /** * Get the output filename from the input YAML filename */ function getOutputFilename(yamlFilename) { // openapi_commerce.yaml -> openapi_commerce_overview.mdx const base = path.basename(yamlFilename, '.yaml'); return `${base}_overview.mdx`; } /** * Main function */ async function main() { console.log('Extracting OpenAPI overviews...\n'); // Ensure output directory exists if (!fs.existsSync(OUTPUT_DIR)) { fs.mkdirSync(OUTPUT_DIR, { recursive: true }); console.log(`Created output directory: ${OUTPUT_DIR}\n`); } // Get all YAML files const yamlFiles = fs.readdirSync(OPENAPI_DIR) .filter(f => f.endsWith('.yaml') || f.endsWith('.yml')) .sort(); console.log(`Found ${yamlFiles.length} YAML files\n`); const results = []; for (const filename of yamlFiles) { const filepath = path.join(OPENAPI_DIR, filename); const yamlContent = fs.readFileSync(filepath, 'utf8'); const overview = extractOverview(yamlContent); if (overview) { const outputFilename = getOutputFilename(filename); const outputPath = path.join(OUTPUT_DIR, outputFilename); const mdxContent = generateMdx(overview, filename); fs.writeFileSync(outputPath, mdxContent, 'utf8'); console.log(`[OK] ${filename}`); console.log(` -> ${outputFilename}`); console.log(` Div ID: ${overview.divId}\n`); results.push({ yamlFile: filename, mdxFile: outputFilename, divId: overview.divId, title: htmlToMdx(overview.divContent).title || overview.apiTitle }); } else { console.log(`[--] ${filename} (no overview div found)\n`); } } console.log(`\n${'='.repeat(50)}`); console.log(`Generated ${results.length} overview files in api-overviews/`); console.log(`${'='.repeat(50)}\n`); // Update docs.json updateDocsJson(results); return results; } /** * Update docs.json to include overview pages */ function updateDocsJson(results) { console.log('Updating docs.json...\n'); const docsJson = JSON.parse(fs.readFileSync(DOCS_JSON_PATH, 'utf8')); // Create a map from yaml filename to mdx path const yamlToMdx = {}; for (const result of results) { // openapi_commerce.yaml -> api-overviews/openapi_commerce_overview const mdxPath = `api-overviews/${result.mdxFile.replace('.mdx', '')}`; yamlToMdx[`openapi/${result.yamlFile}`] = mdxPath; } // Find the API reference group and update it let updatedCount = 0; for (const tab of docsJson.navigation.tabs) { for (const group of tab.groups) { if (group.group === 'API reference' && Array.isArray(group.pages)) { // Update each API group to include overview page for (let i = 0; i < group.pages.length; i++) { const page = group.pages[i]; if (typeof page === 'object' && page.openapi) { const overviewMdx = yamlToMdx[page.openapi]; if (overviewMdx) { // Convert to new format with pages array including overview group.pages[i] = { group: page.group, pages: [ overviewMdx, { openapi: page.openapi } ] }; updatedCount++; console.log(` Updated: ${page.group}`); } } } } } } // Write updated docs.json fs.writeFileSync(DOCS_JSON_PATH, JSON.stringify(docsJson, null, 2) + '\n', 'utf8'); console.log(`\nUpdated ${updatedCount} navigation entries in docs.json`); } // Run the script main().catch(console.error);