Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

sync-docs-config.ts

278 lines7.2 KB

1import { readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
2import { basename, extname, join, resolve } from 'node:path'
3import { fileURLToPath } from 'node:url'
4​
5const __dirname = fileURLToPath(new URL('.', import.meta.url))
6const docsRoot = resolve(__dirname, '../docs')
7const configPath = resolve(docsRoot, 'config.json')
8​
9// Folders to ignore when crawling
10const IGNORED_FOLDERS = ['framework', 'protocol', 'reference']
11​
12// Define the preferred order of sections (folders not listed here will be appended at the end)
13const SECTION_ORDER = ['getting-started', 'guides', 'api', 'adapters']
14​
15// Special label overrides for specific folder names
16const LABEL_OVERRIDES: Record<string, string> = {
17 api: 'API',
19​
20interface DocChild {
21 label: string
22 to: string
23 order?: number
25​
26interface DocSection {
27 label: string
28 children: Array<DocChild>
29 collapsible?: boolean
30 defaultCollapsed?: boolean
32​
33interface DocConfig {
34 $schema?: string
35 docSearch?: {
36 appId: string
37 apiKey: string
38 indexName: string
39 }
40 sections: Array<DocSection>
42​
43interface FrontmatterData {
44 title: string | null
45 order: number | null
47​
48/**
49 * Converts a folder name to a label (e.g., "getting-started" -> "Getting Started")
50 */
51function folderNameToLabel(folderName: string): string {
52 // Check for override first
53 if (LABEL_OVERRIDES[folderName]) {
54 return LABEL_OVERRIDES[folderName]
55 }
56​
57 return folderName
58 .split('-')
59 .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
60 .join(' ')
62​
63/**
64 * Extracts the title and order from frontmatter in a markdown file
65 */
66function extractFrontmatterData(filePath: string): FrontmatterData {
67 try {
68 const content = readFileSync(filePath, 'utf-8')
69 const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/)
70​
71 if (!frontmatterMatch) {
72 return { title: null, order: null }
73 }
74​
75 const frontmatter = frontmatterMatch[1]
76 const titleMatch = frontmatter?.match(/^title:\s*(.+)$/m)
77 const orderMatch = frontmatter?.match(/^order:\s*(\d+)$/m)
78​
79 let title: string | null = null
80 if (titleMatch && titleMatch[1]) {
81 // Remove quotes if present
82 title = titleMatch[1].replace(/^["']|["']$/g, '').trim()
83 }
84​
85 let order: number | null = null
86 if (orderMatch && orderMatch[1]) {
87 order = parseInt(orderMatch[1], 10)
88 }
89​
90 return { title, order }
91 } catch {
92 return { title: null, order: null }
93 }
95​
96/**
97 * Gets all markdown files in a directory and generates children entries
98 */
99function getChildrenFromFolder(
100 folderPath: string,
101 folderName: string,
102): Array<DocChild> {
103 const children: Array<DocChild> = []
104​
105 try {
106 const files = readdirSync(folderPath)
107​
108 for (const file of files) {
109 const filePath = join(folderPath, file)
110 const stat = statSync(filePath)
111​
112 if (stat.isFile() && extname(file) === '.md') {
113 const fileNameWithoutExt = basename(file, '.md')
114 const { title, order } = extractFrontmatterData(filePath)
115​
116 const child: DocChild = {
117 label: title || folderNameToLabel(fileNameWithoutExt),
118 to: `${folderName}/${fileNameWithoutExt}`,
119 }
120​
121 if (order !== null) {
122 child.order = order
123 }
124​
125 children.push(child)
126 }
127 }
128​
129 // Sort children by order (items with order come first, sorted by order value)
130 // Items without order go at the end in arbitrary order
131 children.sort((a, b) => {
132 if (a.order !== undefined && b.order !== undefined) {
133 return a.order - b.order
134 }
135 if (a.order !== undefined) {
136 return -1
137 }
138 if (b.order !== undefined) {
139 return 1
140 }
141 return 0
142 })
143​
144 // Remove order property from children before returning (it's only used for sorting)
145 return children.map(({ label, to }) => ({ label, to }))
146 } catch (error) {
147 console.error(`Error reading folder ${folderPath}:`, error)
148 }
149​
150 return children
152​
153/**
154 * Crawls the docs folder and generates sections
155 */
156function generateSections(): Array<DocSection> {
157 const sectionsMap = new Map<string, DocSection>()
158​
159 try {
160 const entries = readdirSync(docsRoot)
161​
162 for (const entry of entries) {
163 const entryPath = join(docsRoot, entry)
164 const stat = statSync(entryPath)
165​
166 // Skip if not a directory, is ignored, or is a special file
167 if (
168 !stat.isDirectory() ||
169 IGNORED_FOLDERS.includes(entry) ||
170 entry.startsWith('.')
171 ) {
172 continue
173 }
174​
175 const children = getChildrenFromFolder(entryPath, entry)
176​
177 if (children.length > 0) {
178 sectionsMap.set(entry, {
179 label: folderNameToLabel(entry),
180 children,
181 })
182 }
183 }
184 } catch (error) {
185 console.error('Error crawling docs folder:', error)
186 }
187​
188 // Sort sections based on SECTION_ORDER
189 const sortedSections: Array<DocSection> = []
190​
191 // First, add sections in the preferred order
192 for (const folderName of SECTION_ORDER) {
193 const section = sectionsMap.get(folderName)
194 if (section) {
195 sortedSections.push(section)
196 sectionsMap.delete(folderName)
197 }
198 }
199​
200 // Then, add any remaining sections not in the preferred order
201 for (const section of sectionsMap.values()) {
202 sortedSections.push(section)
203 }
204​
205 return sortedSections
207​
208/**
209 * Reads the config.json and updates sections while preserving other fields
210 */
211function updateConfig(newSections: Array<DocSection>): void {
212 let config: DocConfig
213​
214 try {
215 const configContent = readFileSync(configPath, 'utf-8')
216 config = JSON.parse(configContent)
217 } catch (error) {
218 console.error('Error reading config.json:', error)
219 return
220 }
221​
222 // Get labels of newly generated sections
223 const newSectionLabels = new Set(newSections.map((s) => s.label))
224​
225 // Filter out old sections that will be replaced by new ones
226 const preservedSections = config.sections.filter(
227 (section) => !newSectionLabels.has(section.label),
228 )
229​
230 // Find the insertion point - we want to insert new sections before the reference sections
231 // Reference sections typically have "collapsible" property
232 const firstCollapsibleIndex = preservedSections.findIndex(
233 (s) => s.collapsible,
234 )
235​
236 let updatedSections: Array<DocSection>
237​
238 if (firstCollapsibleIndex === -1) {
239 // No collapsible sections, just append new sections
240 updatedSections = [...newSections, ...preservedSections]
241 } else {
242 // Insert new sections before collapsible sections
243 updatedSections = [
244 ...newSections,
245 ...preservedSections.slice(firstCollapsibleIndex),
246 ]
247 }
248​
249 // Update config with new sections
250 config.sections = updatedSections
251​
252 // Write back to config.json with proper formatting
253 try {
254 writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8')
255 console.log('✅ config.json has been updated successfully!')
256 } catch (error) {
257 console.error('Error writing config.json:', error)
258 }
260​
261/**
262 * Main function
263 */
264function main(): void {
265 console.log('🔍 Scanning docs folder...\n')
266​
267 const newSections = generateSections()
268​
269 console.log('📝 Generated sections:')
270 for (const section of newSections) {
271 console.log(` - ${section.label} (${section.children.length} items)`)
272 }
273 console.log('')
274​
275 updateConfig(newSections)
277​
278main()