🚀 Enhanced Documentation System

Overview

We've completely redesigned the documentation system to provide automatic directory discovery, multi-language support, and intelligent content management. This system addresses both improvement requests:

✅ Improvement #1: Unified System with Automatic Discovery

• One source of truth: DocumentationService handles all logic
• Automatic discovery: Scans directory structure and builds routes dynamically
• Manual overrides: NavigationService provides structure customization
• Intelligent syncing: Merges discovered files with manual navigation

✅ Improvement #2: Multi-Language Support

• Directory structure: assets/docs/english/ and assets/docs/spanish/
• File naming: Support for .md and .es.md extensions
• Language detection: Intelligent language detection with fallbacks
• Seamless switching: Easy language switching via DocumentationService

🏗️ New Architecture

Services Separation

Key Features

• 🔍 Automatic Discovery: Scans file system and builds structure
• 🌐 Multi-Language: English/Spanish support with intelligent detection
• 🎯 Manual Overrides: NavigationService provides structure customization
• ⚡ Performance: Intelligent caching and lazy loading
• 🛠️ Developer Tools: Built-in debugging and development utilities

📁 Directory Structure

apps/docs-angular/src/assets/docs/
├── english/                    # English documentation
│   ├── getting-started/
│   ├── guide/
│   ├── development/
│   ├── apps/
│   ├── libs/
│   ├── troubleshooting/
│   └── examples/
├── spanish/                    # Spanish documentation (future)
│   └── [same structure as english]
├── index.md               # English homepage
├── index.es.md                # Spanish homepage
└── docs-manifest.json         # Generated structure manifest

🚀 Quick Start

1. Scan Documentation Structure

# Generate manifest of all documentation files
yarn docs:scan

# Watch for changes and auto-scan
yarn docs:scan:watch

# Get statistics only
yarn docs:stats

2. Add New Documentation

Simply add a .md file in the appropriate language directory:

# Create new file
echo "# My New Guide" > apps/docs-angular/src/assets/docs/english/guide/my-new-guide.md

# Scan to discover it
yarn docs:scan

The system will automatically:

• Discover the new file
• Extract title and metadata
• Add it to navigation structure
• Generate appropriate routes

3. Language Support

// Switch language programmatically
const docService = inject(DocumentationService);
await docService.switchLanguage('es');

// Load content for specific language
const content = await docService.loadContent('/guide/feature', 'es');

4. Manual Navigation Overrides

Edit services/navigation.service.ts to customize navigation:

readonly navigationStructure = signal<NavigationItem[]>([
  {
    text: '🚀 Getting Started',
    order: 1,
    items: [
      { text: 'Introduction', link: '/getting-started', order: 1 },
      // Add your custom items here
    ]
  }
]);

🛠️ Development Tools

Available Commands

# Documentation development  
yarn docs:dev              # Start docs dev server
yarn docs:scan             # Scan documentation structure
yarn docs:scan:watch       # Watch and auto-scan changes
yarn docs:stats            # Get documentation statistics

# Structure management
yarn docs:build            # Build documentation
yarn docs:preview          # Preview production build

Service APIs

// DocumentationService
const stats = docService.documentationStats();
await docService.refreshStructure();
const exists = await docService.contentExists('/path', 'en');

// NavigationService  
const navItem = navService.getNavigationItem('/path');
await navService.syncWithDocumentationService();

// MarkdownService
markdownService.clearCache();
const cacheStats = markdownService.getCacheStats();

📊 File Naming & Detection

Priority Order for Language Detection

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

Path Resolution Order

When loading content, the system tries these paths in order:

1. /assets/docs/english/guide/feature.md
2. /assets/docs/guide/feature.md (legacy)

🔄 Migration from Old System

Automatic Migration

Most content should work automatically. The system provides backward compatibility for:

• Old file paths
• Existing route structure
• Legacy naming conventions

Manual Steps

1. Move Files (Optional): Move files to language directories for cleaner organization
2. Update References: Update any hardcoded file paths in components
3. Test Navigation: Verify all navigation links work
4. Scan Structure: Run yarn docs:scan to generate manifest

🎯 Benefits

For Developers

• ✅ No manual route configuration - automatic discovery
• ✅ Type safety - strong typing throughout
• ✅ Development tools - built-in debugging utilities
• ✅ Clear separation - distinct service responsibilities

For Content Creators

• ✅ Simple workflow - just add .md files
• ✅ Multi-language ready - easy translation support
• ✅ Flexible organization - automatic + manual structure
• ✅ Rich metadata - frontmatter support

For Users

• ✅ Fast performance - intelligent caching
• ✅ Responsive navigation - real-time updates
• ✅ Language switching - seamless transitions
• ✅ Consistent experience - unified interface

📋 Scripts Overview

Main Scanner Script

• Location: apps/docs-angular/scripts/scan-docs-structure.js
• Purpose: Scans directory structure and generates manifest
• Output: apps/docs-angular/src/assets/docs-manifest.json

Package.json Scripts

{
  "docs:scan": "node apps/docs-angular/scripts/scan-docs-structure.js",
  "docs:scan:watch": "nodemon --watch apps/docs-angular/src/assets/docs --ext md --exec 'yarn docs:scan'",
  "docs:stats": "node apps/docs-angular/scripts/scan-docs-structure.js --stats-only"
}

🔮 Future Enhancements

• Real-time watching: Automatic updates when files change
• Content validation: Link checking and validation
• Search integration: Language-aware search
• Build optimization: Pre-generate manifest during build

🚨 Troubleshooting

Common Issues

Debug Commands

// Check system status
console.log(docService.documentationStats());
console.log(navService.currentSection());
console.log(markdownService.getCacheStats());

// Verify file discovery
const exists = await docService.contentExists('/guide/feature', 'en');
const structure = await docService.scanDocumentationStructure('en');

📞 Support

For questions or issues with the enhanced documentation system:

1. Check the Enhanced Documentation System Guide
2. Review service APIs and interfaces
3. Use built-in debugging tools
4. Run yarn docs:scan to refresh structure

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