#!/usr/bin/env node /** * Generate sitemap.xml for Mintlify docs. * - Includes only page content (.md/.mdx) * - Includes top-level changelog.mdx but excludes any files under a changelog/ directory * - Handles locales via directory prefixes (e.g., es/, fr-CA/) * - Adds xhtml:link hreflang alternates for available language variants * - Overwrites /sitemap.xml at the project root */ const fs = require('fs'); const path = require('path'); const { execSync } = require('child_process'); const WORKSPACE_ROOT = path.resolve(__dirname, '..'); const OUTPUT_PATH = path.join(WORKSPACE_ROOT, 'sitemap.xml'); const DOCS_JSON_PATH = path.join(WORKSPACE_ROOT, 'docs.json'); // Directories to skip entirely when walking const SKIP_DIRS = new Set([ '.git', '.github', '.next', 'node_modules', 'scripts', 'images', 'logo', '.cache', 'dist', 'build', 'public', ]); // Allow-list of content roots per locale (relative to locale root) const ALLOWED_CONTENT_ROOTS = new Set([ 'index.mdx', 'index.md', 'changelog.mdx', 'changelog.md', 'getting-started', 'core-concepts', 'troubleshooting', 'community', 'help', ]); // File-level excludes const EXCLUDE_FILES = new Set([ 'README.md', ]); function readJsonSafe(filePath) { try { const raw = fs.readFileSync(filePath, 'utf8'); return JSON.parse(raw); } catch (e) { return null; } } function getCanonicalOrigin() { const docs = readJsonSafe(DOCS_JSON_PATH); const defaultOrigin = 'https://support.openphone.com'; if (!docs) return defaultOrigin; try { const c = docs.seo && docs.seo.metatags && docs.seo.metatags.canonical; if (typeof c === 'string' && c.trim().length > 0) return c.trim().replace(/\/$/, ''); } catch (_) {} return defaultOrigin; } function getLanguages() { const docs = readJsonSafe(DOCS_JSON_PATH); const langs = ['en']; if (!docs) return langs; try { const arr = docs.navigation && docs.navigation.languages; if (Array.isArray(arr)) { for (const entry of arr) { if (entry && typeof entry.language === 'string' && entry.language.trim()) { if (entry.language === 'en') { if (!langs.includes('en')) langs.unshift('en'); } else if (!langs.includes(entry.language)) { langs.push(entry.language); } } } } } catch (_) {} return langs; } function isMdLike(file) { return file.endsWith('.md') || file.endsWith('.mdx'); } function shouldSkipDir(dirName) { return SKIP_DIRS.has(dirName); } function normalizeToPosix(relativePath) { return relativePath.split(path.sep).join('/'); } function isUnderChangelogDir(posixPath) { // Exclude any path that contains "/changelog/" (localized or not) return /(^|\/)changelog\//.test(posixPath); } function isAllowedContentRelativeToLocaleRoot(posixRel) { // posixRel is relative to a locale root (e.g., '', 'es', 'fr-CA') const firstSegment = posixRel.split('/')[0]; if (!firstSegment) return false; if (ALLOWED_CONTENT_ROOTS.has(firstSegment)) return true; // directories // Also allow direct index/changelog at root if (ALLOWED_CONTENT_ROOTS.has(posixRel)) return true; return false; } function walk(dir) { const out = []; const stack = [dir]; while (stack.length) { const current = stack.pop(); const entries = fs.readdirSync(current, { withFileTypes: true }); for (const entry of entries) { const full = path.join(current, entry.name); const rel = path.relative(WORKSPACE_ROOT, full); const relPosix = normalizeToPosix(rel); if (entry.isDirectory()) { if (shouldSkipDir(entry.name)) continue; // Only traverse content roots for default and locale prefixes const isLocaleRoot = relPosix === 'es' || relPosix === 'fr-CA'; const isRoot = relPosix === '' || relPosix === '.'; if (isLocaleRoot) { // Traverse inside locale root only allowed content const allowedChildren = fs.readdirSync(full, { withFileTypes: true }); for (const child of allowedChildren) { const childRel = normalizeToPosix(path.relative(WORKSPACE_ROOT, path.join(full, child.name))); if (child.isDirectory()) { if (ALLOWED_CONTENT_ROOTS.has(child.name)) stack.push(path.join(full, child.name)); } else if (isMdLike(child.name) && ALLOWED_CONTENT_ROOTS.has(child.name)) { out.push(path.join(full, child.name)); } } continue; } if (isRoot) { // At the very top level, traverse only allowed content roots and locale dirs const allowedTopChildren = fs.readdirSync(full, { withFileTypes: true }); for (const child of allowedTopChildren) { const childFull = path.join(full, child.name); if (child.isDirectory()) { if (ALLOWED_CONTENT_ROOTS.has(child.name) || child.name === 'es' || child.name === 'fr-CA') { stack.push(childFull); } } else if (isMdLike(child.name) && ALLOWED_CONTENT_ROOTS.has(child.name)) { out.push(childFull); } } continue; } // For nested directories under allowed roots, traverse normally stack.push(full); continue; } // Files if (!isMdLike(entry.name)) continue; if (EXCLUDE_FILES.has(entry.name)) continue; if (isUnderChangelogDir(relPosix)) continue; // exclude dated changelogs // Keep it; actual allow-list enforcement is handled by limiting traversal above out.push(full); } } return out; } function detectLangAndSlug(posixPath) { // Returns { lang: 'en'|'es'|'fr-CA'|..., slug: 'path/without/ext' } let lang = 'en'; let slug = posixPath.replace(/\.(md|mdx)$/i, ''); if (slug.startsWith('es/')) { lang = 'es'; slug = slug.slice(3); } else if (slug.startsWith('fr-CA/')) { lang = 'fr-CA'; slug = slug.slice('fr-CA/'.length); } return { lang, slug }; } function routeFrom(lang, slug) { if (slug === 'index') { return lang === 'en' ? '/' : `/${lang}`; } return lang === 'en' ? `/${slug}` : `/${lang}/${slug}`; } function getLastModISO(filePath) { try { const out = execSync(`git log -1 --format=%cI -- ${JSON.stringify(path.relative(WORKSPACE_ROOT, filePath))}`, { cwd: WORKSPACE_ROOT, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', }).trim(); if (out) return out; } catch (_) {} try { const stat = fs.statSync(filePath); return new Date(stat.mtimeMs).toISOString(); } catch (_) { return new Date().toISOString(); } } function escapeXml(str) { return str .replace(/&/g, '&') .replace(//g, '>') .replace(/"/g, '"') .replace(/'/g, '''); } function main() { const origin = getCanonicalOrigin(); const languages = getLanguages(); // e.g., ['en', 'es', 'fr-CA'] // Walk and gather all eligible markdown files const files = walk(WORKSPACE_ROOT) .map((abs) => normalizeToPosix(path.relative(WORKSPACE_ROOT, abs))) .filter((p) => isMdLike(p)); // Ensure top-level changelog files are included if present for (const lang of languages) { const rel = lang === 'en' ? 'changelog.mdx' : `${lang}/changelog.mdx`; const altRel = rel.replace(/\.mdx$/, '.md'); const abs = path.join(WORKSPACE_ROOT, rel); const absAlt = path.join(WORKSPACE_ROOT, altRel); if (fs.existsSync(abs)) { const posix = normalizeToPosix(path.relative(WORKSPACE_ROOT, abs)); if (!files.includes(posix)) files.push(posix); } else if (fs.existsSync(absAlt)) { const posix = normalizeToPosix(path.relative(WORKSPACE_ROOT, absAlt)); if (!files.includes(posix)) files.push(posix); } } // Group by normalized slug (without locale prefix) const groups = new Map(); // key: slug, value: Map(lang => { file, route, lastmod }) for (const relPosix of files) { // Enforce allow-list relative to locale root const { lang, slug } = detectLangAndSlug(relPosix); const relWithinLocale = lang === 'en' ? relPosix : relPosix.slice((lang + '/').length); if (!isAllowedContentRelativeToLocaleRoot(relWithinLocale)) continue; if (slug.includes('/changelog/')) continue; // extra safety const route = routeFrom(lang, slug); const abs = path.join(WORKSPACE_ROOT, relPosix); const lastmod = getLastModISO(abs); if (!groups.has(slug)) groups.set(slug, new Map()); groups.get(slug).set(lang, { file: relPosix, route, lastmod }); } // Build XML entries for each language variant const urlEntries = []; const allSlugsSorted = Array.from(groups.keys()).sort(); for (const slug of allSlugsSorted) { const variants = groups.get(slug); const langsAvailable = languages.filter((l) => variants.has(l)); if (langsAvailable.length === 0) continue; // Build alternates list (href per language) const alternates = langsAvailable.map((l) => ({ lang: l, href: origin + variants.get(l).route, })); // Also compute x-default (prefer 'en' if present) const xDefaultHref = origin + (variants.has('en') ? variants.get('en').route : variants.get(langsAvailable[0]).route); // Create one per available language variant for (const lang of langsAvailable) { const { route, lastmod } = variants.get(lang); const loc = origin + route; const altLinks = alternates .map((a) => ` `) .join('\n'); const entry = [ ' ', ` ${escapeXml(loc)}`, ` ${escapeXml(lastmod)}`, altLinks, ` `, ' ', ].join('\n'); urlEntries.push(entry); } } const xml = [ '', '', ...urlEntries, '', ].join('\n'); fs.writeFileSync(OUTPUT_PATH, xml, 'utf8'); console.log(`Wrote ${OUTPUT_PATH} with ${urlEntries.length} entries.`); } main();

Getting started

Core concepts

Troubleshooting

Contact Support

Community