Enhanced Documentation System

Complete guide to the new automatic documentation discovery and multi-language system

Enhanced Documentation System

Our documentation system has been completely redesigned to provide automatic directory discovery, multi-language support, and intelligent content management. This guide explains how to use the new system effectively.

🏗️ System Architecture

The new documentation system consists of three main services that work together:

1. DocumentationService

2. NavigationService

3. MarkdownService

🌐 Multi-Language Support

Directory Structure

assets/docs/
├── english/           # English documentation
│   ├── getting-started/
│   ├── guide/
│   ├── apps/
│   └── libs/
├── spanish/           # Spanish documentation (future)
│   ├── getting-started/
│   └── ...
├── index.md      # English homepage
└── index.es.md       # Spanish homepage

File Naming Conventions

  1. Standard Files: filename.md (placed in language directory)
  2. Language-Specific: filename.md or filename.es.md
  3. Index Files: index.md and index.es.md in root

Language Detection Priority

  1. Directory-based: Files in /english/ or /spanish/ directories
  2. Extension-based: Files with .md or .es.md extensions
  3. Service state: Current language setting in DocumentationService
  4. Default: English (en)

🔍 Automatic Directory Discovery

How It Works

  1. Directory Scanning: The system automatically scans the assets/docs/ directory structure
  2. File Discovery: Identifies all .md files and their metadata
  3. Structure Building: Creates a hierarchical structure of sections and files
  4. Navigation Sync: Merges discovered files with manual navigation overrides

Manual Override System

The NavigationService contains manual navigation structure that takes priority over discovered files:

readonly navigationStructure = signal<NavigationItem[]>([
  {
    text: '🚀 Getting Started',
    order: 1,
    items: [
      { text: 'Introduction', link: '/getting-started', order: 1 },
      { text: 'Project Overview', link: '/guide/project-overview', order: 2 }
    ]
  }
  // ... more sections
]);

Sync Process

  1. Check Natural Structure: Scan filesystem for available files
  2. Compare with Manual: Compare discovered structure with NavigationService
  3. Merge Intelligently: Add new files to navigation while preserving manual overrides
  4. Update Navigation: Automatically update navigation structure

🚀 Using the New System

Adding New Documentation

  1. Create File: Add your .md file in the appropriate language directory:

    assets/docs/english/guide/my-new-guide.md

  2. Run Discovery: The system will automatically discover it on next scan

  3. Manual Override (Optional): Add specific navigation entry in NavigationService if needed:

    { text: 'My New Guide', link: '/guide/my-new-guide', order: 3 }

Language-Specific Content

  1. English Version: assets/docs/english/guide/feature.md
  2. Spanish Version: assets/docs/spanish/guide/feature.md
  3. Language Extensions: Alternatively use feature.md and feature.es.md

Switching Languages

// In a component
constructor() {
  const docService = inject(DocumentationService);
  
  // Switch to Spanish
  docService.switchLanguage('es');
  
  // Current language
  const currentLang = docService.currentLanguage();
}

🛠️ Development Tools

Automatic Structure Scanner

Run the directory scanner to generate a manifest of all available files:

cd apps/docs-angular
node scripts/scan-docs-structure.js

This generates src/assets/docs-manifest.json with complete structure information.

Development Commands

# Clear documentation cache
docService.clearCache();

# Check if content exists
const exists = await docService.contentExists('/guide/feature', 'en');

# Get cache statistics
const stats = docService.getCacheStats();

# Refresh structure
await docService.refreshStructure();

📊 Advanced Features

Intelligent Path Resolution

The system tries multiple path patterns to find files:

  1. /assets/docs/english/guide/feature.md (primary English path)
  2. /assets/docs/spanish/guide/feature.md (Spanish localized path)
  3. /assets/docs/guide/feature.md (legacy fallback)
  4. /assets/docs/feature.md (root fallback)

Content Caching

Fallback Content

When files are not found, the system provides localized fallback content:

🔄 Migration Guide

From Old System

  1. Move Files: Move documentation files to language directories:

    mkdir -p assets/docs/english
mv assets/docs/*.md assets/docs/english/

  2. Update References: Update any hardcoded file references in components

  3. Test Navigation: Verify all navigation links work with new structure

  4. Clean Up: Remove old routing entries that are now handled dynamically

Best Practices

  1. Consistent Structure: Keep similar directory structures across languages
  2. Meaningful Names: Use descriptive directory and file names
  3. Manual Overrides: Use NavigationService overrides for custom ordering
  4. Regular Scanning: Run the structure scanner after adding new files

🚨 Troubleshooting

Common Issues

  1. File Not Found: Check path resolution order and file naming
  2. Navigation Missing: Verify NavigationService includes the section
  3. Language Not Working: Check language detection priority
  4. Cache Issues: Clear cache during development

Debugging Tools

// Check documentation statistics
const stats = docService.documentationStats();

// Verify file existence
const exists = await docService.contentExists(path, language);

// Check navigation item
const navItem = navService.getNavigationItem(path);

// Review cache contents
const cacheStats = markdownService.getCacheStats();

🎯 Benefits

For Developers

For Content Creators

For Users

📈 Future Enhancements

This enhanced system provides a robust foundation for documentation management while maintaining flexibility for future growth and localization needs.