import fs from 'fs/promises' import path from 'path' import { pathToFileURL } from 'url' import { isDirectRun } from './is-direct-run' import { extractSidebarDocIds, type SidebarItem } from './sidebar-doc-ids' /** * Validates that every MDX file under the content directories is referenced * in its corresponding sidebars.js. Catches "ghost pages" that exist on disk but are not linked in any sidebar. * * Usage: * pnpm validate:sidebar-docs */ export interface SectionConfig { name: string contentDir: string sidebarPath: string sidebarKey: string } export const SECTIONS: SectionConfig[] = [ { name: 'docs', contentDir: 'src/content/en/docs', sidebarPath: 'src/content/en/docs/sidebars.js', sidebarKey: 'docsSidebar', }, { name: 'integrations', contentDir: 'src/content/en/integrations', sidebarPath: 'src/content/en/integrations/sidebars.js', sidebarKey: 'integrationsSidebar', }, { name: 'reference', contentDir: 'src/content/en/reference', sidebarPath: 'src/content/en/reference/sidebars.js', sidebarKey: 'referenceSidebar', }, ] /** Files that are intentionally not in any sidebar */ const IGNORED_PATTERNS = [ /\/_template\.mdx$/, // Template files for authors /\/_partial-.*\.mdx$/, // Partial MDX files that are imported into other docs // Temp ignore for mastra-platform docs that are in the process of moving out of the docs /\/mastra-platform\/.*/, /\/agents\/networks/, /\/license\.mdx$/, ] async function collectMdxFiles(dir: string): Promise { const results: string[] = [] async function walk(current: string): Promise { const entries = await fs.readdir(current, { withFileTypes: true }) const subdirs: Promise[] = [] for (const entry of entries) { const fullPath = path.join(current, entry.name) if (entry.isDirectory()) { subdirs.push(walk(fullPath)) } else if (entry.name.endsWith('.mdx')) { results.push(fullPath) } } await Promise.all(subdirs) } await walk(dir) return results } function shouldIgnore(filePath: string): boolean { return IGNORED_PATTERNS.some(pattern => pattern.test(filePath)) } export interface ValidationResult { section: string ghostPages: string[] } export async function validateSection(section: SectionConfig, rootDir: string): Promise { const sidebarFullPath = path.join(rootDir, section.sidebarPath) const contentFullDir = path.join(rootDir, section.contentDir) const sidebarModule = await import(pathToFileURL(sidebarFullPath).href) const sidebars = sidebarModule.default ?? sidebarModule const items: SidebarItem[] = sidebars[section.sidebarKey] if (!items || !Array.isArray(items)) { throw new Error(`${section.sidebarKey} not found in ${section.sidebarPath}`) } const sidebarIds = extractSidebarDocIds(items) const mdxFiles = await collectMdxFiles(contentFullDir) const ghostPages: string[] = [] for (const filePath of mdxFiles) { if (shouldIgnore(filePath)) continue // Convert file path to doc ID: strip content dir prefix and .mdx extension const relativePath = path.relative(contentFullDir, filePath) const docId = relativePath.replace(/\.mdx$/, '') if (!sidebarIds.has(docId)) { // Show path relative to the content section for readability ghostPages.push(docId) } } return { section: section.name, ghostPages: ghostPages.sort() } } async function main(): Promise { const rootDir = process.cwd() console.log('Checking for docs not linked in sidebars...\n') const results = await Promise.all(SECTIONS.map(section => validateSection(section, rootDir))) const totalGhostPages = results.reduce((sum, r) => sum + r.ghostPages.length, 0) if (totalGhostPages === 0) { console.log('All docs are linked in their sidebars') return } console.log(`Found ${totalGhostPages} doc(s) not linked in any sidebar:\n`) for (const result of results) { if (result.ghostPages.length === 0) continue console.log(` ${result.section}/sidebars.js (${result.ghostPages.length} missing):`) for (const page of result.ghostPages) { console.log(` - ${page}`) } console.log() } console.log('Add the missing docs to their sidebars.js, or add an ignore pattern to scripts/validate-sidebar-docs.ts') process.exit(1) } if (isDirectRun(import.meta.url)) { main().catch(error => { console.error('Unhandled error:', error instanceof Error ? error.message : error) process.exit(1) }) }