Documentation Loader Hook
Relevant source files
The following files were used as context for generating this wiki page:
The useDocumentationLoader hook is a specialized React custom hook designed to manage the lifecycle of fetching, parsing, and providing metadata for documentation files within the SuperClaude Website architecture. It serves as the primary data abstraction layer for the DocViewerPage, decoupling the UI components from the underlying file structure and network logic required to retrieve Markdown content from the project's static assets.
This hook works in conjunction with a pre-generated docs-map.json file, which acts as a registry for all available documentation. By coordinating between URL parameters (category and filename) and this registry, the hook provides a standardized state object containing the document's raw content, metadata, loading status, and any errors encountered during the retrieval process.
Architecture and Data Flow
The documentation loading system relies on a build-time manifest generation followed by a runtime fetch operation.
Build-Time Manifest Generation
Before the application starts or builds, a Node.js script scans the documentation directory to create a centralized map. This map allows the hook to resolve friendly URL names to actual file paths on the server.
The script scripts/generate-docs-map.js extracts titles from the first H1 header in each Markdown file and organizes them by category.
Sources: scripts/generate-docs-map.js:18-50, package.json:34-35
Runtime Loading Logic
At runtime, the hook uses the category and file parameters to locate the correct entry in the docs-map.json. It then executes an asynchronous fetch request to retrieve the physical file.
Implementation Details
Hook Signature and State
The hook maintains four primary state variables to provide a comprehensive status of the documentation request.
| State Variable | Type | Description |
|---|---|---|
markdown | String | The raw text content of the Markdown file. |
doc | Object | Metadata from docs-map.json including title, name, and path. |
loading | Boolean | True while the fetch operation is in progress. |
error | Error/Null | Contains error information if the fetch or lookup fails. |
Sources: src/hooks/useDocumentationLoader.js:4-38
Integration with UI Components
The DocViewerPage consumes the hook to render the documentation. It utilizes the loading state to show an animation and the error state to display a fallback UI if the document fails to load.
// Usage in DocViewerPage.js
const { markdown, doc, loading, error } = useDocumentationLoader(category, file);
if (loading) return <LoadingSpinner />;
if (error) return <ErrorMessage error={error} />;
if (!doc) return <NotFoundPage />;
return <ReactMarkdown>{markdown}</ReactMarkdown>;
Sources: src/pages/DocViewerPage.js:23-45
Supporting Infrastructure
Documentation Mapping
The mapping logic ensures that documentation can be organized into categories and retrieved reliably. The categories are sorted based on a predefined categoryOrder.
| Category Order | Description |
|---|---|
Getting-Started | Initial setup and installation guides. |
User-Guide | General usage instructions. |
Reference | Technical specifications and API details. |
Developer-Guide | Architecture and contribution guides. |
Templates | Pre-defined configurations and patterns. |
Sources: scripts/generate-docs-map.js:7-13
Link Resolution
While the loader handles fetching the current file, the resolveMarkdownLink utility works with the data provided by the hook to enable cross-document navigation. It translates standard Markdown relative links into React Router-compatible paths using the docs-map.json.
Sources: src/utils/linkResolver.js:27-48
Conclusion
The useDocumentationLoader hook is a central pillar of the SuperClaude Website's content delivery system. By abstracting the complexities of file fetching and manifest lookups, it allows the documentation viewer to focus on rendering and user interaction while ensuring that content remains synchronized with the physical file structure of the repository.