Guide Based Auto Guide System

Comprehensive documentation system guides

🎯 Guide-Based Auto-Guide System - Stable & Predictable

✅ New Strategy Implemented

The docs-angular system now uses a stable, predictable guide-based approach instead of complex auto-detection logic.

🎯 How It Works

📁 Guide.md Files

Every directory that should support auto-guides now has a guide.md file:

apps/
├── guide.md                    ← Controls /apps route
├── singularity/
│   └── guide.md               ← Controls /apps/singularity route
├── editor-web/
│   └── guide.md               ← Controls /apps/editor-web route
├── space-map/
│   └── guide.md               ← Controls /apps/space-map route
└── ux-test/
    └── guide.md               ← Controls /apps/ux-test route

🔧 Auto-Guide Trigger

A guide.md file triggers auto-guide when it contains:

Option 1: Auto-Guide Marker

<!-- AUTO-GUIDE -->

This marker tells the system to show the beautiful auto-guide.

Option 2: Empty/Minimal Content

📄 Custom Guide Content

If guide.md contains substantial content (50+ characters), it shows that content instead of the auto-guide.

🔄 Decision Flow

graph TD
    A[Route Accessed] --> B{guide.md exists?}
    B -->|Yes| C{Contains AUTO-GUIDE marker?}
    B -->|No| H[Fallback: Check for children]
    
    C -->|Yes| D[Show Auto-Guide]
    C -->|No| E{Content < 50 chars?}
    
    E -->|Yes| D
    E -->|No| F[Show Guide Content]
    
    H -->|Has children| D
    H -->|No children| G[Try to load regular content]
    
    D --> I[Beautiful Auto-Guide with Cards]
    F --> J[Custom Guide Content]
    G --> K[Regular Markdown Content]

🛠️ Implementation Details

📋 DocsPageComponent Logic

private smartLoadContent(path: string): void {
  // 1. Try to load guide.md first
  const guidePath = cleanPath === '/' ? '/guide' : `${cleanPath}/guide`;
  
  this.markdownService.loadContent(guidePath, 'en').subscribe({
    next: (guideContent) => {
      // 2. Check if it's an auto-guide marker
      if (this.isAutoGuideMarker(guideContent.content)) {
        this.showAutoGuide.set(true); // Show auto-guide
      } else {
        this.content.set(guideContent); // Show guide content
      }
    },
    error: () => {
      // 3. Fallback to children detection
      this.fallbackToChildrenDetection(cleanPath);
    }
  });
}

🎯 Auto-Guide Marker Detection

private isAutoGuideMarker(content: string): boolean {
  const trimmedContent = content.trim();
  
  // Check for explicit marker
  if (trimmedContent.includes('<!-- AUTO-GUIDE -->')) {
    return true;
  }
  
  // Check if essentially empty
  const contentWithoutMarker = trimmedContent.replace(/<!--[\s\S]*?-->/g, '').trim();
  return contentWithoutMarker.length < 50;
}

🎯 Benefits of New System

✅ Predictable

✅ Stable

✅ Flexible

✅ Maintainable

📝 Usage Examples

🎯 Creating Auto-Guide for New Section

# 1. Create directory
mkdir apps/docs-angular/src/assets/docs/english/my-section

# 2. Add content files
echo "# Feature 1" > apps/docs-angular/src/assets/docs/english/my-section/feature-1.md
echo "# Feature 2" > apps/docs-angular/src/assets/docs/english/my-section/feature-2.md

# 3. Create guide.md for auto-guide
cat > apps/docs-angular/src/assets/docs/english/my-section/guide.md << 'EOF'
<!-- AUTO-GUIDE -->

Auto-guide for my-section with all features.
EOF

# 4. Regenerate manifest
node apps/docs-angular/scripts/scan-docs-structure.js

# Result: /my-section shows beautiful auto-guide with Feature 1 & Feature 2 cards! ✨

🎨 Creating Custom Guide

# Create guide.md with substantial content
cat > apps/docs-angular/src/assets/docs/english/my-section/guide.md << 'EOF'
# My Section Guide

This is a custom guide with specific instructions for this section.

## Getting Started
Follow these steps...

## Advanced Usage
For advanced features...
EOF

# Result: /my-section shows custom guide content instead of auto-guide

🔄 Switching Between Auto-Guide and Custom

# Switch to auto-guide
echo "<!-- AUTO-GUIDE -->" > apps/docs-angular/src/assets/docs/english/my-section/guide.md

# Switch to custom guide
echo "# Custom Guide Content..." > apps/docs-angular/src/assets/docs/english/my-section/guide.md

🚀 Migration from Old System

✅ All Apps Already Migrated

🔄 Fallback System

The system still includes fallback logic for routes without guide.md:

  1. First: Try to find guide.md
  2. If not found: Check for children (old logic)
  3. If no children: Load regular content

This ensures zero breaking changes while providing the new stable system.

🔍 Debugging Guide

🐛 Auto-Guide Not Showing

  1. Check guide.md exists: /path/to/section/guide.md
  2. Verify marker: Contains <!-- AUTO-GUIDE --> or is < 50 chars
  3. Check console: Look for guide-based loading messages
  4. Verify children: Ensure section has child content

📄 Content Not Loading

  1. Check guide.md content: If > 50 chars, it shows as content
  2. Remove marker: Delete <!-- AUTO-GUIDE --> if you want content
  3. Check file structure: Ensure content files exist

🔄 Fallback Issues

  1. Add guide.md: Create explicit guide.md for predictable behavior
  2. Check manifest: Ensure node apps/docs-angular/scripts/scan-docs-structure.js was run
  3. Verify routes: Check navigation structure for correct paths

🎯 Best Practices

📁 Directory Structure

my-section/
├── guide.md                    ← Controls section behavior
├── overview.md                 ← Content files
├── getting-started.md
└── advanced-features.md

🎯 Guide.md Patterns

<!-- For auto-guide -->
<!-- AUTO-GUIDE -->

Brief description of what this section contains.

<!-- For custom guide -->
# Section Guide

Custom guide content with specific instructions...

📋 Naming Conventions

🌟 Conclusion

The new guide-based system provides:

🎯 For Users

🛠️ For Developers

📈 For Growth

Your docs-angular system now has rock-solid, predictable auto-guide behavior! 🚀