> ## Documentation Index
> Fetch the complete documentation index at: https://mint-tsdocs.saulo.engineer/llms.txt
> Use this file to discover all available pages before exploring further.
# Navigation Layer
> Dedicated navigation management for Mintlify documentation sites
## Overview
The navigation layer provides dedicated management of Mintlify documentation navigation structures, extracted from the main document generation logic to improve modularity and maintainability.
**Primary Component**: `src/navigation/NavigationManager.ts`
## Key Responsibilities
Organizes API documentation by item types (Classes, Interfaces, Functions, etc.)
Handles reading, updating, and writing Mintlify's docs.json configuration
Supports both simple navigation arrays and tab-based structures
Automatically categorizes API items with appropriate icons
## Navigation Structure
The NavigationManager supports two Mintlify navigation formats:
### Simple Navigation Array
```json theme={null}
{
"navigation": [
{
"group": "API Reference",
"pages": ["api/class1", "api/class2"]
}
]
}
```
### Mintlify v4 Tab Structure
```json theme={null}
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Classes",
"pages": ["api/class1", "api/class2"]
}
]
}
]
}
}
```
## API Item Categorization
Each API item type gets an appropriate icon:
| API Item Type | Icon | Display Name |
| ----------------------- | ----------- | ------------ |
| `ApiItemKind.Class` | `box` | Classes |
| `ApiItemKind.Interface` | `plug` | Interfaces |
| `ApiItemKind.Function` | `function` | Functions |
| `ApiItemKind.TypeAlias` | `file-code` | Types |
| `ApiItemKind.Variable` | `variable` | Variables |
| `ApiItemKind.Enum` | `list` | Enums |
| `ApiItemKind.Namespace` | `folder` | Namespaces |
Pages are automatically grouped by API item type:
1. **Classes** - All class documentation
2. **Interfaces** - All interface documentation
3. **Functions** - All function documentation
4. **Types** - All type alias documentation
5. **Variables** - All variable documentation
6. **Enums** - All enum documentation
7. **Namespaces** - All namespace documentation
n
Each group is sorted alphabetically for easy navigation.
## Key Methods
**Add API Item to Navigation**
Automatically categorizes and adds an API item:
```typescript theme={null}
public addApiItem(apiItem: ApiItem, filename: string): void
```
* Validates that the item should be in top-level navigation
* Calculates relative path from docs.json to output file
* Normalizes path separators for cross-platform compatibility
* Prevents duplicate entries
**Example**:
```typescript theme={null}
navigationManager.addApiItem(apiClass, 'my-package.myclass.mdx');
```
**Generate and Write Navigation**
Creates the final navigation structure:
```typescript theme={null}
public async generateNavigation(): Promise
```
**Process**:
1. Validates docs.json file path using security utilities
2. Reads existing docs.json (if it exists)
3. Generates hierarchical navigation structure
4. Merges with existing navigation
5. Validates JSON size (10MB limit)
6. Writes updated docs.json
**Safety Features**:
* File path validation
* JSON content validation
* Size limit enforcement
* Secure file operations
**Create Hierarchical Structure**
Generates the navigation hierarchy:
```typescript theme={null}
public generateHierarchicalNavigation(): any[]
```
**Returns**:
```typescript theme={null}
[
{
"group": "Classes",
"icon": "box",
"pages": ["api/class1.mdx", "api/class2.mdx"]
},
{
"group": "Interfaces",
"icon": "plug",
"pages": ["api/interface1.mdx", "api/interface2.mdx"]
}
]
```
## Configuration Options
```typescript NavigationManagerOptions theme={null}
interface NavigationManagerOptions {
/**
* Path to the docs.json file
*/
docsJsonPath?: string;
/**
* Tab name in Mintlify navigation (default: "Code Reference")
*/
tabName?: string;
/**
* Group name within the tab
*/
groupName?: string;
/**
* Enable menu for the group in navigation
*/
enableMenu?: boolean;
/**
* Output folder path for path calculations
*/
outputFolder?: string;
}
```
```typescript Example Usage theme={null}
const navigationManager = new NavigationManager({
docsJsonPath: './docs/docs.json',
tabName: 'API Reference',
groupName: 'Generated API',
enableMenu: true,
outputFolder: './docs/api'
});
```
## Integration with MarkdownDocumenter
The NavigationManager is integrated into the document generation workflow:
Created during `MarkdownDocumenter` construction with configuration options
Each generated page calls `addApiItem()` to register with navigation
After all pages are generated, `generateNavigation()` is called
Navigation statistics are included in final performance reports
## Security Features
Uses `SecurityUtils.validateFilePath()` to ensure:
* Paths are within allowed directories
* No directory traversal attempts
* Safe file operations
Uses `SecurityUtils.validateJsonContent()` to:
* Validate JSON structure
* Prevent malicious content
* Ensure data integrity
Enforces maximum JSON size of 10MB to:
* Prevent memory exhaustion
* Ensure reasonable file sizes
* Maintain performance
## Error Handling
The NavigationManager provides comprehensive error handling:
```typescript theme={null}
// Navigation-specific errors with detailed context
throw new DocumentationError(
`Failed to add API item to navigation: ${apiItem.displayName}`,
ErrorCode.NAVIGATION_ERROR,
{
resource: apiItem.displayName,
operation: 'addApiItem',
cause: error,
suggestion: 'Check file permissions and ensure the docs.json path is correct'
}
);
```
## Performance Benefits
Separated navigation logic reduces coupling and improves maintainability
Duplicate prevention eliminates redundant processing
All navigation items collected before final generation
## Related Documentation
See how NavigationManager integrates with document generation
Learn about performance optimization