#!/usr/bin/env node import { execSync } from 'child_process' import { existsSync, mkdirSync, rmSync, readdirSync, readFileSync, writeFileSync, statSync, } from 'fs' import { join, dirname, relative, basename, extname } from 'path' import { fileURLToPath } from 'url' import https from 'https' import http from 'http' const __dirname = dirname(fileURLToPath(import.meta.url)) // Parse command line arguments const args = process.argv.slice(2) const localFlagIndex = args.indexOf('--local') const isLocalMode = localFlagIndex !== -1 const localRepoPath = isLocalMode && args[localFlagIndex + 1] ? args[localFlagIndex + 1] : null // Configuration const CONFIG = { repoUrl: 'https://github.com/filamentphp/filament.git', latestVersion: '5.x', branches: ['5.x', '4.x', '3.x', '2.x', '1.x'], // Legacy branches pull from HEAD; all others pull from the latest tag legacyBranches: ['1.x', '2.x', '3.x'], reposDir: join(__dirname, '.repos'), docsDir: __dirname, templateFile: join(__dirname, 'docs.template.json'), outputFile: join(__dirname, 'docs.json'), // Package order for navigation packageOrder: [ 'panels', 'admin', 'tables', 'schemas', 'forms', 'infolists', 'actions', 'notifications', 'widgets', 'support', ], sponsorsApiUrl: 'https://filamentphp.com/api/sponsors', } function exec(cmd, options = {}) { console.log(` $ ${cmd}`) try { return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], ...options, }) } catch (error) { if (options.ignoreError) { return null } throw error } } function copyDirectoryRecursive(srcDir, destDir) { // Recursively copy all files and directories if (!existsSync(srcDir)) return 0 mkdirSync(destDir, { recursive: true }) let count = 0 const entries = readdirSync(srcDir, { withFileTypes: true }) for (const entry of entries) { const srcPath = join(srcDir, entry.name) const destPath = join(destDir, entry.name) if (entry.isDirectory()) { count += copyDirectoryRecursive(srcPath, destPath) } else { writeFileSync(destPath, readFileSync(srcPath)) count++ } } return count } function cleanVersionDirectories() { console.log('\nStep 1: Cleaning up existing version directories...') for (const branch of CONFIG.branches) { const dir = join(CONFIG.docsDir, branch) if (existsSync(dir)) { console.log(` Removing ${branch}/`) rmSync(dir, { recursive: true, force: true }) } // Also clean up images directory for this version const imagesDir = join(CONFIG.docsDir, 'images', branch) if (existsSync(imagesDir)) { console.log(` Removing images/${branch}/`) rmSync(imagesDir, { recursive: true, force: true }) } } } function syncRepository() { console.log('\nStep 2: Syncing repository...') // Always sync the remote bare repo (needed for other branches) mkdirSync(CONFIG.reposDir, { recursive: true }) const repoDir = join(CONFIG.reposDir, 'filament.git') if (existsSync(repoDir)) { console.log(' Repository exists, fetching updates...') exec( `git --git-dir="${repoDir}" fetch origin '+refs/heads/*:refs/heads/*' --prune`, ) } else { console.log(' Cloning repository...') exec(`git clone --bare "${CONFIG.repoUrl}" "${repoDir}"`) } // In local mode, also validate the local repo let workTree = null if (isLocalMode) { if (!localRepoPath) { console.error( ' ERROR: No path provided. Usage: node sync --local ', ) process.exit(1) } if (!existsSync(localRepoPath)) { console.error(` ERROR: Local repository not found at ${localRepoPath}`) process.exit(1) } const gitDir = join(localRepoPath, '.git') if (!existsSync(gitDir)) { console.error(` ERROR: Not a git repository: ${localRepoPath}`) process.exit(1) } console.log( ` Using local repository at ${localRepoPath} for current branch`, ) workTree = localRepoPath } return { gitDir: repoDir, workTree } } function getLatestTagForBranch(gitDir, branch) { // Get the latest tag for a branch (e.g., v5.x.x for 5.x branch) // Tags are expected to follow semver format: v{major}.{minor}.{patch} const majorVersion = branch.replace('.x', '') // Fetch tags to ensure we have them exec(`git --git-dir="${gitDir}" fetch origin --tags`, { ignoreError: true }) // Get all tags matching this major version, sorted by version number descending const tagsOutput = exec( `git --git-dir="${gitDir}" tag -l "v${majorVersion}.*" --sort=-v:refname`, { ignoreError: true }, ) if (!tagsOutput?.trim()) { return null } // Return the first (latest) tag const tags = tagsOutput.trim().split('\n') return tags[0] || null } function getCurrentBranch(workTree) { // Get the current branch from a working tree const result = exec(`git -C "${workTree}" rev-parse --abbrev-ref HEAD`) return result.trim() } function getLocalBranch(repo) { if (!repo.workTree) return null const branch = getCurrentBranch(repo.workTree) console.log(` Local branch: ${branch}`) if (!CONFIG.branches.includes(branch)) { console.log(` WARNING: Branch ${branch} is not in expected branches list`) console.log(` Expected branches: ${CONFIG.branches.join(', ')}`) console.log(` Proceeding anyway...`) } return branch } function stripNumericPrefix(name) { // Remove leading numeric prefixes like "01-", "01_", "01 " from file/directory names return name.replace(/^\d+[-_\s]+/, '') } function replaceOutsideCodeBlocks(text, pattern, replacement) { // Apply a regex replacement only outside of fenced code blocks return text .split(/(```[\s\S]*?```)/g) .map((segment, i) => i % 2 === 0 ? segment.replace(pattern, replacement) : segment, ) .join('') } function transformRadioGroupToTabs(text) { // Transform RadioGroup + Alpine.js x-show pattern to Mintlify Tabs // First, normalize x-show divs by removing extra attributes and newlines text = replaceOutsideCodeBlocks( text, //g, '

', ) text = replaceOutsideCodeBlocks( text, //g, '

', ) // Remove x-data wrapper divs text = replaceOutsideCodeBlocks(text, //g, '') // Process RadioGroups one at a time let iterations = 0 const maxIterations = 10 while (text.includes('([\s\S]*?)<\/RadioGroup>/, ) if (!rgMatch) break const modelName = rgMatch[1] const rgContent = rgMatch[2] const fullRgMatch = rgMatch[0] // Parse options from RadioGroup const options = [] const optRegex = /\s*([\s\S]*?)\s*\s*([\s\S]*?)\s*<\/span>\s*<\/RadioGroupOption>/g let optMatch while ((optMatch = optRegex.exec(rgContent)) !== null) { options.push({ value: optMatch[1], label: optMatch[2].trim(), description: optMatch[3].trim(), }) } if (options.length === 0) { text = text.replace(fullRgMatch, '') continue } // Find and extract content for each option from x-show divs const tabs = [] for (const opt of options) { // Build regex to match x-show div with this option's value // Match until next x-show div, RadioGroup, or end of file const xShowStartRegex = new RegExp( `

`, 'g', ) const startMatch = xShowStartRegex.exec(text) let content = '' if (startMatch) { const startIdx = startMatch.index + startMatch[0].length // Find the matching closing

by counting depth let depth = 1 let endIdx = startIdx for (let i = startIdx; i < text.length && depth > 0; i++) { if (text.slice(i, i + 4) === '') { depth-- if (depth === 0) { endIdx = i break } } } content = text.slice(startIdx, endIdx).trim() // Remove the entire x-show div from text const fullXShowDiv = text.slice(startMatch.index, endIdx + 6) // +6 for

text = text.replace(fullXShowDiv, '') } tabs.push({ title: opt.label, content: opt.description + (content ? '\n\n' + content : ''), }) } // Build Tabs markup let tabsHtml = '\n' for (const tab of tabs) { tabsHtml += ` \n` tabsHtml += ` ${tab.content.split('\n').join('\n ')}\n` tabsHtml += ` \n` } tabsHtml += '\n' // Replace RadioGroup with Tabs text = text.replace(fullRgMatch, tabsHtml) } // Clean up orphaned closing

tags on their own lines (but not inside code blocks) text = replaceOutsideCodeBlocks(text, /^\s*<\/div>\s*$/gm, '') // Clean up multiple consecutive blank lines text = text.replace(/\n{4,}/g, '\n\n\n') return text } function copyWithStrippedPrefixes( srcDir, destDir, fileMapping = new Map(), srcBase = null, destBase = null, pathPrefix = '', version = null, ) { // Recursively copy files/directories while stripping numeric prefixes from names // Also builds a mapping from stripped relative paths to original relative paths for ordering if (!existsSync(srcDir)) return fileMapping // Initialize base paths on first call if (srcBase === null) srcBase = srcDir if (destBase === null) destBase = destDir mkdirSync(destDir, { recursive: true }) const entries = readdirSync(srcDir, { withFileTypes: true }) for (const entry of entries) { // Skip _PACKAGES marker files if (entry.name.includes('_PACKAGES')) continue const srcPath = join(srcDir, entry.name) let strippedName = stripNumericPrefix(entry.name) // Rename contributing.md to contributing.mdx to work around a Mintlify bug if (strippedName === 'contributing.md') { strippedName = 'contributing.mdx' } const destPath = join(destDir, strippedName) if (entry.isDirectory()) { copyWithStrippedPrefixes( srcPath, destPath, fileMapping, srcBase, destBase, pathPrefix, version, ) } else { // Copy file let content = readFileSync(srcPath) // Transform markdown files: replace @components/*.astro imports with /snippets/*.jsx using named imports if (entry.name.endsWith('.md') || entry.name.endsWith('.mdx')) { let textContent = content.toString('utf-8') // Transform: import ComponentName from '@components/ComponentName.astro' // To: import { ComponentName } from '/snippets/ComponentName.jsx' textContent = textContent.replace( /import\s+(\w+)\s+from\s+['"]@components\/(.+?)\.astro['"]/g, "import { $1 } from '/snippets/$2.jsx'", ) // Transform Astro slot syntax to React props for Disclosure component // \n Title\n Content\n // becomes: \n Content\n textContent = textContent.replace( /\s*\n\s*([^<]+)<\/span>\s*\n/g, '\n', ) // Replace contents: false with mode: "wide" in frontmatter textContent = textContent.replace( /^(---\s*\n[\s\S]*?)contents:\s*false([\s\S]*?\n---)/, '$1mode: "wide"$2', ) // Transform RadioGroup + Alpine.js x-show pattern to Mintlify Tabs textContent = transformRadioGroupToTabs(textContent) // Remove RadioGroup/RadioGroupOption imports since we're using Tabs now textContent = textContent.replace( /import\s*{\s*RadioGroup\s*}\s*from\s*['"][^'"]+['"]\s*\n?/g, '', ) textContent = textContent.replace( /import\s*{\s*RadioGroupOption\s*}\s*from\s*['"][^'"]+['"]\s*\n?/g, '', ) // Transform Checkboxes to CheckboxGroup // Replace Checkboxes import with CheckboxGroup import (include ConditionalDisclosure) textContent = textContent.replace( /import\s*{\s*Checkboxes\s*}\s*from\s*['"][^'"]+['"]/g, "import { CheckboxGroup, Checkbox, ConditionalDisclosure } from '/snippets/CheckboxGroup.jsx'", ) // Remove separate Checkbox import if present (now bundled with CheckboxGroup) textContent = textContent.replace( /import\s*{\s*Checkbox\s*}\s*from\s*['"][^'"]+['"]\s*\n?/g, '', ) // Transform to // Extract model from first Checkbox inside textContent = textContent.replace( /\s*\n(\s*]*model="(\w+)")/g, '\n$1', ) textContent = textContent.replace(/<\/Checkboxes>/g, '') // Transform Checkbox with slot description to props // Need to handle each checkbox individually to avoid cross-matching // First, process checkboxes WITH descriptions textContent = textContent.replace( /\s*((?:(?!\s*([\s\S]*?)\s*<\/span>\s*<\/Checkbox>/g, (match, value, label, desc) => { return `${label.trim()}` }, ) // Transform Checkbox without description (no span inside) textContent = textContent.replace( /\s*((?:(?!/g, (match, value, label) => { return `${label.trim()}` }, ) // Transform Disclosure with x-show to ConditionalDisclosure with showWhen and model props // becomes textContent = textContent.replace( //g, (match, openAttr, condition) => { // Extract model from condition like "packages.includes('forms')" const modelMatch = condition.match(/^(\w+)\.includes/) const model = modelMatch ? modelMatch[1] : 'packages' return `` }, ) // Also need to close with // This is tricky - we need to match the opening tag and its closing tag // For now, transform opening tags, then handle closing tags separately // Transform Disclosure/ConditionalDisclosure with slot summary // Title // becomes: textContent = textContent.replace( /<(ConditionalDisclosure|Disclosure)(\s+open)?(\s+showWhen="[^"]+")?(\s+model="[^"]+")?>\s*\n?\s*([^<]+)<\/span>/g, '<$1$2$3$4 summary="$5">', ) // Replace closing tags that correspond to ConditionalDisclosure openings // We need to find ConditionalDisclosure and replace its closing tag // Simple approach: if we have ConditionalDisclosure in the file, replace matching after them if (textContent.includes(' that follows ConditionalDisclosure content textContent = textContent.replace( /(]*>[\s\S]*?)<\/Disclosure>/g, '$1', ) } // Transform Aside components to native Mintlify callouts // → ... // → ... // → ... const asideVariantMap = { info: 'Info', warning: 'Warning', tip: 'Tip', note: 'Note', danger: 'Danger', check: 'Check', } textContent = textContent.replace( /([\s\S]*?)<\/Aside>/g, (match, variant, content) => { const component = asideVariantMap[variant] || 'Note' return `<${component}>${content}` }, ) // Remove Aside import since we're using native Mintlify callouts textContent = textContent.replace( /import\s*{\s*Aside\s*}\s*from\s*['"][^'"]+['"]\s*\n?/g, '', ) // Ensure blank line after imports (MDX requires this) // Match: import line followed immediately by non-import content textContent = textContent.replace( /(import\s*{[^}]+}\s*from\s*['"][^'"]+['"]\s*\n)([A-Z]|\w+[^i])/g, '$1\n$2', ) // Add ./ prefix to relative markdown links that don't have a path prefix // Matches links that don't start with: protocol://, protocol:, ../, /, ./, # textContent = textContent.replace( /\[([^\]]+)\]$(?!(?:\w+:|\.\.\/|\/|\.\/|#))([^)]+)$/g, '[$1](./$2)', ) // Compute GitHub path for EditOnGitHub component const relativeSourcePath = relative(srcBase, srcPath) const gitHubPath = pathPrefix ? `packages/${pathPrefix}/docs/${relativeSourcePath}` : `docs/${relativeSourcePath}` // Add Footer and EditOnGitHub imports to every page // Insert import after frontmatter (if present) or at the top const frontmatterEndMatch = textContent.match( /^---\s*\n[\s\S]*?\n---\s*\n/, ) const imports = "import { Footer } from '/snippets/Footer.jsx'\n" + "import { EditOnGitHub } from '/snippets/EditOnGitHub.jsx'\n" if (frontmatterEndMatch) { const insertPos = frontmatterEndMatch[0].length textContent = textContent.slice(0, insertPos) + imports + textContent.slice(insertPos) } else { textContent = imports + textContent } // Ensure blank line between imports and content // Match the last import line and ensure there's a blank line after it textContent = textContent.replace( /(import\s+(?:\w+|\{[^}]+\})\s+from\s*['"][^'"]+['"]\s*\n)(?!\s*\n)(?!import\s)/g, '$1\n', ) // Add Warning for non-latest versions if (version && version !== CONFIG.latestVersion) { // Calculate smart link - check if page/directory exists in latest version const relPath = relative(destBase || destDir, destPath).replace( /\.(mdx|md)$/, '', ) const latestVersionDir = join(CONFIG.docsDir, CONFIG.latestVersion) let smartLink = `/${CONFIG.latestVersion}` // Check if exact page exists in latest version const latestPageMd = join(latestVersionDir, relPath + '.md') const latestPageMdx = join(latestVersionDir, relPath + '.mdx') if (existsSync(latestPageMd) || existsSync(latestPageMdx)) { // Exact page exists smartLink = `/${CONFIG.latestVersion}/${relPath}` } else { // Check if a parent directory exists in latest version const pathParts = relPath.split('/') for (let i = pathParts.length - 1; i >= 0; i--) { const dirPath = join( latestVersionDir, ...pathParts.slice(0, i + 1), ) if (existsSync(dirPath) && statSync(dirPath).isDirectory()) { smartLink = `/${CONFIG.latestVersion}/${pathParts.slice(0, i + 1).join('/')}` break } } } // Find the position after imports (after the last import line and its following blank line) const importRegex = /^import\s+.+$/gm let lastImportEnd = 0 let match while ((match = importRegex.exec(textContent)) !== null) { lastImportEnd = match.index + match[0].length } if (lastImportEnd > 0) { // Skip any whitespace/newlines after the last import let insertPos = lastImportEnd while ( insertPos < textContent.length && (textContent[insertPos] === '\n' || textContent[insertPos] === ' ') ) { insertPos++ } const warningText = `\nYou are currently viewing the documentation for Filament ${version}, which is a previous version of Filament.\n\nLooking for the current stable version? Visit the [${CONFIG.latestVersion} documentation](${smartLink}).\n\n\n` textContent = textContent.slice(0, insertPos) + warningText + textContent.slice(insertPos) } } // Add EditOnGitHub and Footer components at the end textContent = textContent.trimEnd() + `\n\n\n\n

​Overview

Overview