MDC Troubleshooting Guide

Common issues and solutions for MDC component rendering and functionality

🔧 MDC Troubleshooting Guide

This guide helps you diagnose and fix common issues with MDC components not rendering properly.

🚨 Common Issues

Issue 1: Components Show as Empty Dark Blocks

Symptoms:

Components appear as empty dark rectangles with copy icons
No interactive content is displayed
Components are not functioning as expected

Root Causes:

Component Not Registered: The MDC component is not properly registered in the component registry
Parser Issues: The MDC parser is not correctly parsing the component syntax
Renderer Problems: The MDC renderer is not properly rendering the components
Mock Components: The system is using mock components instead of real implementations

Solutions:

Check Component Registration

<mdc:code-block language="typescript"> // Verify component is registered in MDCRendererService private initializeComponentRegistry(): void { this.registerComponent('mdc-code-block', CodeBlockComponent); this.registerComponent('mdc-interactive-demo', InteractiveDemoComponent); this.registerComponent('mdc-diagram', DiagramComponent); // ... other components }

Verify Component Syntax

<mdc:code-block language="markdown">

<mdc:code-block language="typescript"> export class ExampleComponent { @Input() title = 'Hello World'; }

<mdc:code-block language="typescript">
export class ExampleComponent {
  @Input() title = 'Hello World';
}
</mdc:code-block>

Enable Debug Mode

<mdc:code-block language="yaml">

In frontmatter

ui: showDebugInfo: true showComponentInfo: true

Issue 2: Components Not Parsed Correctly

Symptoms:

Components appear as plain text instead of rendered components
Frontmatter parsing errors
Component properties not recognized

Solutions:

Check Frontmatter Syntax

<mdc:code-block language="yaml">

title: "Document Title" type: mdc interactive: true status: published

Component definitions

components:

code-block
interactive-demo
diagram

UI configuration

ui: showMetadata: true enableInteraction: true

Verify Component Properties

<mdc:code-block language="markdown">

<mdc:code-block language="typescript" interactive="true" theme="vs-dark">

// Code content

<mdc:code-block language=typescript interactive=true theme=vs-dark>

// Code content

Issue 3: Performance Issues

Symptoms:

Slow component rendering
Page load timeouts
Memory leaks

Solutions:

Enable Lazy Loading

<mdc:code-block language="yaml">

In frontmatter

performance: lazyLoad: true preload: false cacheStrategy: normal maxRenderTime: 10000 componentTimeout: 5000

Optimize Component Usage

<mdc:code-block language="markdown">

<mdc:interactive-demo component="HeavyComponent" lazy="true" placeholder="Loading component...">

Issue 4: Styling and Theme Problems

Symptoms:

Components don't match the theme
Styling conflicts
Responsive design issues

Solutions:

Check Theme Integration

<mdc:code-block language="scss"> // Ensure components inherit theme variables .mdc-component { background: var(--ux-surface); color: var(--ux-on-surface); border: 1px solid var(--ux-outline); border-radius: var(--ux-border-radius); }

Verify CSS Classes

<mdc:code-block language="html">

🔍 Debugging Steps

Step 1: Enable Debug Information

<mdc:code-block language="yaml">

In frontmatter

ui: showDebugInfo: true showComponentInfo: true showMetadata: true

Step 2: Check Browser Console

<mdc:code-block language="javascript"> // Look for these error messages in console: // - "Component not found: mdc-code-block" // - "Failed to parse MDC component" // - "Rendering timeout exceeded" // - "Invalid component properties"

Step 3: Verify Component Registration

<mdc:code-block language="typescript"> // Check if components are registered console.log('Registered components:', this.componentRegistry.keys());

// Verify component exists const component = this.componentRegistry.get('mdc-code-block'); if (!component) { console.error('Component mdc-code-block not registered'); }

Step 4: Test Component Parsing

<mdc:code-block language="typescript"> // Test MDC parsing const testContent = <mdc:code-block language="typescript"> export class TestComponent {} </mdc:code-block>;

const result = await this.parserService.parseMDCContent(testContent); console.log('Parsed components:', result.components);

🛠️ Quick Fixes

Fix 1: Convert Markdown Code Blocks to MDC Components

Problem: Components wrapped in markdown code blocks Solution: Remove the markdown wrapper

<mdc:code-block language="markdown">

<mdc:code-block language="typescript">
export class ExampleComponent {}
</mdc:code-block>

<mdc:code-block language="typescript"> export class ExampleComponent {}

Fix 2: Correct Property Syntax

Problem: Missing quotes around property values Solution: Add proper quotes

<mdc:code-block language="markdown">

<mdc:code-block language=typescript interactive=true>

<mdc:code-block language="typescript" interactive="true">

Fix 3: Fix JSON Properties

Problem: Invalid JSON in component properties Solution: Validate JSON syntax

<mdc:code-block language="markdown">

<mdc:interactive-demo :props='{"variant": "primary", "size": "large"}'>

📊 Diagnostic Tools

Component Status Checker

<mdc:interactive-demo component="ComponentStatusChecker" :props='{"showAllComponents": true}'>

This tool checks the status of all MDC components.

Performance Monitor

<mdc:live-data source="/api/mdc/performance" refresh="5s" template="performance-monitor" fallback="Loading performance data...">

Error Reporter

<mdc:conditional condition="user.role === 'developer'" fallback="Developer access required for error reporting">

<mdc:interactive-demo component="ErrorReporter" :props='{"autoReport": true}'>

🎯 Prevention Tips

1. Use Proper Syntax

Always use quotes around property values
Validate JSON in component properties
Don't wrap MDC components in markdown code blocks

2. Test Components

Test components in isolation first
Use debug mode during development
Verify component registration

3. Monitor Performance

Enable performance profiling
Use lazy loading for heavy components
Monitor memory usage

4. Keep Components Updated

Regularly update component implementations
Check for breaking changes in updates
Test after any system updates

🔗 Additional Resources

📞 Getting Help

If you're still experiencing issues:

Check the Console: Look for error messages in browser console
Enable Debug Mode: Set showDebugInfo: true in frontmatter
Test Minimal Example: Create a simple MDC file with one component
Contact Support: Reach out to the development team with specific error messages

This troubleshooting guide is maintained by the GoGrab Development Team and is updated regularly based on common issues and solutions.