Link Resolution Logic

Introduction

The Link Resolution Logic in the SuperClaude Website framework is a specialized system designed to manage and resolve hyperlinks within Markdown-based documentation. Since the documentation is stored as physical files in the public/docs/ directory but served via a dynamic React-based viewer, the system must translate standard Markdown file links (e.g., ./example.md) into valid Single Page Application (SPA) routes.

This logic ensures that internal anchors, relative paths between documentation files, and external links are handled correctly by the UI. It relies on a pre-generated documentation map to validate paths and maintain consistency across the application.

Sources: src/utils/linkResolver.js, src/pages/DocViewerPage.js:154-184, scripts/generate-docs-map.js

Path Resolution and Mapping

The core of the link resolution system relies on two primary mechanisms: a static documentation map generated at build time and a utility library that processes relative paths.

Documentation Map Generation

The generate-docs-map.js script scans the public/docs directory to create a JSON manifest (docs-map.json). This manifest acts as the source of truth for the link resolver, containing the category, file name, display title, and physical path for every document.

The script organizes documents based on a predefined categoryOrder (Getting-Started, User-Guide, etc.) to ensure structural consistency.
Sources: scripts/generate-docs-map.js:6-54

The ResolvePath Utility

The resolvePath function calculates the absolute path of a target file based on the current file's location. It handles standard directory navigation syntax like .. (parent directory) and . (current directory).

Sources: src/utils/linkResolver.js:3-25

Markdown Link Processing

When a user interacts with a link inside a rendered Markdown document, the DocViewerPage intercepts the request and applies specific logic based on the link's format.

Resolution Flow

The system categorizes links into three distinct types:

1. Anchor Links: Links starting with # are treated as internal fragments. They use a scrollToHash function for smooth scrolling and update the browser history without a page reload.
2. Markdown Document Links: Links ending in .md are passed to resolveMarkdownLink. This function validates the target against docsMap and returns a standard SPA route (/docs/:category/:name).
3. External Links: All other links are treated as external and opened in a new tab using target="_blank".

Integration with UI Components

The link resolution logic is integrated into the routing and navigation components to provide a seamless experience.

Documentation Loader

The useDocumentationLoader hook utilizes the parameters (category, file) resolved from the URL to fetch the raw Markdown content from the server. It matches the URL parameters against the docsMap to find the correct file path.
Sources: src/hooks/useDocumentationLoader.js:15-30

Sidebar Navigation

The Sidebar component groups documents by their categories defined in the docsMap. It uses NavLink to highlight the active document based on the resolved route.
Sources: src/components/Sidebar.js:31-41

Code Implementation Detail

The resolveMarkdownLink function specifically cleans the .md extension to match the routing structure of the React application.

// src/utils/linkResolver.js:41-47
const [path, hash] = href.split('#');
const resolvedPath = resolvePath(currentDocInMap.path, path);
const cleanedPath = resolvedPath.replace(/\.md$/, '');
const linkedDoc = docsMap.find(d => d.path.replace(/\.md$/, '') === cleanedPath);

if (!linkedDoc) return null;
const to = `/docs/${linkedDoc.category}/${linkedDoc.name}`;

Sources: src/utils/linkResolver.js:41-47

Conclusion

Link Resolution Logic is a critical middleware layer in the SuperClaude Website. By abstracting the physical file structure into a logical routing system and dynamically resolving relative paths, it allows the documentation to remain portable as standard Markdown while providing a modern, integrated browsing experience.