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