MDC File Support Implementation Plan

Comprehensive plan for adding .mdc file support to the docs-angular app for future-proof AI-enhanced documentation

📋 MDC File Support Implementation Plan

🎯 Project Overview

Enhance the docs-angular app to support .mdc (Markdown Components) files alongside existing .md files, creating a future-proof documentation system that leverages AI capabilities and advanced component-based authoring.

🔍 What are MDC Files?

MDC (Markdown Components) files are an evolution of traditional Markdown that supports:

🏗️ Technical Architecture

Phase 1: Core Infrastructure (Week 1-2)

1.1 File Detection & Discovery

1.2 Content Loading System

1.3 Routing & Navigation

Phase 2: MDC Parser & Renderer (Week 2-3)

2.1 MDC Parser Development

interface MDCContent {
  frontmatter: MDCFrontmatter;
  components: MDCComponent[];
  markdown: string;
  metadata: AIMetadata;
}

interface MDCComponent {
  type: 'angular' | 'widget' | 'interactive' | 'ai-generated';
  selector: string;
  props: Record<string, any>;
  content?: string;
  position: number;
}

interface AIMetadata {
  generatedBy?: string;
  lastAIUpdate?: string;
  aiPrompts?: string[];
  confidence?: number;
  reviewStatus?: 'pending' | 'approved' | 'needs-revision';
}

2.2 Enhanced Markdown Renderer

2.3 AI Integration Layer

Phase 3: Component System (Week 3-4)

3.1 MDC Component Library

// Core MDC Components
@Component({ selector: 'mdc-code-block' })
export class MDCCodeBlockComponent {
  @Input() language: string;
  @Input() code: string;
  @Input() aiGenerated: boolean;
  @Input() interactive: boolean;
}

@Component({ selector: 'mdc-diagram' })
export class MDCDiagramComponent {
  @Input() type: 'mermaid' | 'flowchart' | 'architecture';
  @Input() data: any;
  @Input() aiPrompt?: string;
}

@Component({ selector: 'mdc-interactive-demo' })
export class MDCInteractiveDemoComponent {
  @Input() component: string;
  @Input() props: Record<string, any>;
  @Input() sandbox: boolean;
}

3.2 Widget Integration

3.3 AI-Enhanced Components

Phase 4: Advanced Features (Week 4-5)

4.1 Interactive Documentation

4.2 AI Content Generation

4.3 Analytics & Insights

🛠️ Implementation Details

File Structure Enhancement

apps/docs-angular/
├── src/
│   ├── app/
│   │   ├── services/
│   │   │   ├── mdc-parser.service.ts          # NEW: MDC file parsing
│   │   │   ├── mdc-renderer.service.ts        # NEW: MDC content rendering
│   │   │   ├── ai-integration.service.ts      # NEW: AI features
│   │   │   └── markdown.service.ts            # ENHANCED: Support .mdc
│   │   ├── components/
│   │   │   ├── mdc-renderer/                  # NEW: MDC rendering component
│   │   │   ├── mdc-components/                # NEW: MDC component library
│   │   │   └── enhanced-markdown-renderer/    # ENHANCED: MDC support
│   │   └── types/
│   │       └── mdc.types.ts                   # NEW: MDC type definitions
│   └── assets/
│       └── docs/
│           ├── english/
│           │   └── **/*.{md,mdc}              # Support both extensions
│           └── spanish/
│               └── **/*.{md,mdc}              # Support both extensions
└── scripts/
    └── scan-docs-structure.js                 # ENHANCED: Detect .mdc files

Service Architecture

Enhanced MarkdownService

@Injectable({ providedIn: 'root' })
export class MarkdownService {
  // Existing methods...
  
  // NEW: Detect file type and load appropriately
  loadContent(path: string, language: string): Observable<ContentResult> {
    return this.detectFileType(path, language).pipe(
      switchMap(fileType => {
        if (fileType === 'mdc') {
          return this.loadMDCContent(path, language);
        } else {
          return this.loadMarkdownContent(path, language);
        }
      })
    );
  }
  
  private loadMDCContent(path: string, language: string): Observable<MDCContentResult> {
    // Load and parse .mdc files
  }
  
  private detectFileType(path: string, language: string): Observable<'md' | 'mdc'> {
    // Try .mdc first, fallback to .md
  }
}

New MDCParserService

@Injectable({ providedIn: 'root' })
export class MDCParserService {
  parseMDCContent(content: string): MDCContent {
    // Parse frontmatter with AI metadata
    // Extract component definitions
    // Process markdown content
    // Return structured MDC content
  }
  
  validateComponents(components: MDCComponent[]): ValidationResult {
    // Validate component selectors exist
    // Check required props
    // Verify component compatibility
  }
  
  optimizeForAI(content: MDCContent): AIOptimizedContent {
    // Structure content for AI processing
    // Extract semantic information
    // Generate content embeddings
  }
}

Component Integration

MDC Renderer Component

@Component({
  selector: 'app-mdc-renderer',
  template: `
    <div class="mdc-content">
      <!-- Render frontmatter metadata -->
      <div class="mdc-metadata" *ngIf="showMetadata">
        <mdc-metadata-display [metadata]="content.metadata"></mdc-metadata-display>
      </div>
      
      <!-- Render mixed markdown and components -->
      <div class="mdc-body">
        <ng-container *ngFor="let section of renderedSections">
          <!-- Markdown sections -->
          <div *ngIf="section.type === 'markdown'" 
               class="markdown-section"
               [innerHTML]="section.html">
          </div>
          
          <!-- Component sections -->
          <ng-container *ngIf="section.type === 'component'">
            <ng-container *ngComponentOutlet="section.component; 
                                            injector: section.injector">
            </ng-container>
          </ng-container>
        </ng-container>
      </div>
      
      <!-- AI enhancement panel -->
      <div class="ai-panel" *ngIf="showAIPanel">
        <mdc-ai-suggestions [content]="content"></mdc-ai-suggestions>
      </div>
    </div>
  `
})
export class MDCRendererComponent {
  @Input() content: MDCContent;
  @Input() showMetadata = false;
  @Input() showAIPanel = false;
  
  renderedSections: RenderedSection[];
  
  ngOnInit() {
    this.renderContent();
  }
  
  private renderContent() {
    // Process MDC content and create rendered sections
  }
}

🎯 MDC File Format Specification

Basic MDC File Structure

---
title: Advanced Component Documentation
description: Interactive documentation with embedded components
type: mdc
version: 1.0
ai:
  generated: false
  lastUpdate: 2025-01-25
  prompts: []
  confidence: 1.0
  reviewStatus: approved
components:
  - name: interactive-demo
    version: 1.2.0
    required: true
  - name: code-playground
    version: 2.0.0
    required: false
---

# Advanced Component Documentation

This is regular markdown content that can include **formatting** and [links](/other-page).

## Interactive Component Demo

<mdc:interactive-demo 
  component="ButtonComponent"
  :props="{ variant: 'primary', size: 'large' }"
  sandbox="true">
  
  This button demonstrates our design system in action.
  
</mdc:interactive-demo>

## Live Code Example

<mdc:code-block 
  language="typescript"
  interactive="true"
  ai-generated="false">
```typescript
@Component({
  selector: 'app-example',
  template: `<button [class]="buttonClass">{{ label }}</button>`
})
export class ExampleComponent {
  @Input() label = 'Click me';
  @Input() variant: 'primary' | 'secondary' = 'primary';
  
  get buttonClass() {
    return `btn btn-${this.variant}`;
  }
}

AI-Generated Content Section

<mdc:ai-content prompt="Explain the benefits of component-based documentation" generated-at="2025-01-25T10:30:00Z" confidence="0.95">

Component-based documentation offers several key advantages:

More regular markdown content continues here...


### **Advanced MDC Features**
```markdown
<!-- Widget Integration -->
<mdc:widget 
  type="theme-preview"
  :config="{ theme: 'dark', components: ['button', 'card'] }">
</mdc:widget>

<!-- Conditional Content -->
<mdc:conditional 
  condition="user.hasAccess('advanced')"
  fallback="Contact admin for advanced features">
  
  Advanced content only visible to authorized users.
  
</mdc:conditional>

<!-- Real-time Data -->
<mdc:live-data 
  source="api/stats"
  refresh="30s"
  template="stats-display">
</mdc:live-data>

<!-- AI-Enhanced Diagrams -->
<mdc:diagram 
  type="architecture"
  ai-prompt="Show the component hierarchy for our design system"
  auto-update="true">
</mdc:diagram>

🚀 Migration Strategy

Backward Compatibility

Content Migration Process

  1. Identify Candidates: Find documentation that would benefit from interactivity
  2. Create .mdc Version: Convert .md to .mdc with enhanced features
  3. Test & Validate: Ensure all components render correctly
  4. Deploy Gradually: Roll out .mdc files in phases
  5. Monitor Performance: Track rendering performance and user engagement

Team Training

📊 Success Metrics

Technical Metrics

User Experience Metrics

Content Quality Metrics

🔧 Development Timeline

Week 1: Foundation

Week 2: Parser & Core Components

Week 3: Advanced Features

Week 4: Integration & Testing

Week 5: Polish & Launch

🎉 Expected Benefits

For Content Authors

For Developers

For Users

For Organization

🔮 Future Possibilities

AI-Powered Features

Advanced Interactions

Integration Ecosystem

This comprehensive plan positions the docs-angular app as a cutting-edge, future-proof documentation platform that leverages the latest in AI and interactive technologies while maintaining full backward compatibility with existing content.