Documentation Map Generation
Relevant source files
The following files were used as context for generating this wiki page:
Documentation Map Generation is a build-time process that scans the project's documentation directory to create a structured registry of available Markdown files. This registry, stored as docs-map.json, serves as the single source of truth for the frontend application to discover, categorize, and link documentation content dynamically. Sources: scripts/generate-docs-map.js:4-5, package.json:33-34
The system ensures that the documentation remains synchronized with the physical file structure in the public/docs directory. By automating this mapping, the project supports a scalable architecture where adding new documentation files requires no manual configuration updates in the UI components. Sources: scripts/generate-docs-map.js:47-48, src/hooks/useDocumentationLoader.js:15-18
Build Lifecycle Integration
The generation process is integrated into the Node.js build lifecycle. It is executed automatically before the development server starts or the production build begins via npm scripts. Sources: package.json:33-34
Execution Trigger
The generate-docs-map.js script is called during the prestart and prebuild phases. This ensures that the documentation registry is always up-to-date before the React application is bundled or served.
| Script Hook | Command | Purpose |
|---|---|---|
prestart | node scripts/generate-docs-map.js | Generates the map before local development. |
prebuild | node scripts/generate-docs-map.js | Generates the map before production deployment. |
Sources: package.json:33-34
Generation Logic and Architecture
The generation script performs a recursive scan of the public/docs directory, extracting metadata from individual Markdown files. Sources: scripts/generate-docs-map.js:16-17
Categorization and Sorting
The script organizes documentation into predefined categories. A strict sorting order is applied to ensure that the documentation menu appears logically to the user.
The diagram shows the sequential flow of reading the filesystem and transforming it into a JSON structure. Sources: scripts/generate-docs-map.js:16-54
Metadata Extraction
For every Markdown file found, the system extracts the following attributes:
- Category: The name of the parent directory.
- Name: The filename without the
.mdextension. - Title: Extracted from the first
#heading in the file; defaults to the filename if no heading is found. - Path: The web-accessible URL path (e.g.,
/docs/Category/file.md).
Sources: scripts/generate-docs-map.js:40-52
Data Schema: docs-map.json
The generated output is a JSON array of objects. This file is imported by various frontend components to drive the UI. Sources: scripts/generate-docs-map.js:58, src/components/Sidebar.js:5
Schema Definition
| Field | Type | Description |
|---|---|---|
category | String | The grouping folder (e.g., "Getting-Started"). |
name | String | URL-friendly identifier based on the filename. |
title | String | Human-readable title extracted from file content. |
path | String | Public path used for fetch operations. |
Sources: scripts/generate-docs-map.js:47-52
Consumption in the Frontend
The generated map is utilized by multiple modules to facilitate navigation and content rendering. Sources: src/hooks/useDocumentationLoader.js:2, src/utils/linkResolver.js:1
Documentation Loading
The useDocumentationLoader hook uses the map to find the correct file path based on URL parameters (category and file). Once identified, it fetches the raw Markdown content from the path specified in the map. Sources: src/hooks/useDocumentationLoader.js:15-22
Navigation and Sidebar
The Sidebar and DocPage components import the map to group documentation by category for display.
The diagram illustrates how the JSON registry acts as the data provider for navigation UI. Sources: src/components/Sidebar.js:27-33, src/pages/DocPage.js:33-39
Link Resolution
The linkResolver.js utility utilizes the map to transform relative Markdown links (e.g., [Link](https://github.com/RemyLoveLogicAI/SuperGemini_Website/blob/HEAD/other.md)) into internal application routes. It cross-references the resolved file path against the entries in docs-map.json to determine the correct application URL. Sources: src/utils/linkResolver.js:32-48
Summary
Documentation Map Generation is a critical preprocessing step that abstracts the filesystem structure into a portable JSON registry. By automating the extraction of titles and category sorting, it enables a dynamic, low-maintenance documentation portal where the UI automatically reflects the underlying content stored in the repository. Sources: scripts/generate-docs-map.js:58, src/hooks/useDocumentationLoader.js:15-22