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 = ['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',
18}
19
20interface DocChild {
21 label: string
22 to: string
23 order?: number
24}
25
26interface DocSection {
27 label: string
28 children: Array<DocChild>
29 collapsible?: boolean
30 defaultCollapsed?: boolean
31}
32
33interface DocConfig {
34 $schema?: string
35 docSearch?: {
36 appId: string
37 apiKey: string
38 indexName: string
39 }
40 sections: Array<DocSection>
41}
42
43interface FrontmatterData {
44 title: string | null
45 order: number | null
46}
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(' ')
61}
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 }
94}
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
151}
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
206}
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 }
259}
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)
276}
277
278main()