Migration Guide: Markdown to MDC

Step-by-step guide for migrating from traditional Markdown files to MDC (Markdown Components) format

🔄 Migration Guide: Markdown to MDC

This guide provides a comprehensive approach to migrating from traditional Markdown files to MDC (Markdown Components) format, enabling interactive documentation with enhanced features.

🎯 Migration Overview

What is MDC?

MDC (Markdown Components) extends traditional Markdown with:

Migration Benefits

📋 Pre-Migration Checklist

1. Assess Current Documentation

2. Plan Migration Strategy

3. Prepare Infrastructure

🚀 Migration Approaches

Approach 1: Gradual Migration (Recommended)

Migrate content incrementally, starting with high-value pages.

Phase 1: High-Impact Pages

Phase 2: Standard Content

Phase 3: Legacy Content

Approach 2: Complete Migration

Migrate all content at once (suitable for smaller documentation sets).

📝 Step-by-Step Migration Process

Step 1: File Preparation

1.1 Rename File

# Rename .md to .mdc
mv getting-started.md getting-started.mdc

1.2 Update Frontmatter

Convert basic frontmatter to MDC format:

Before (.md):

---
title: Getting Started
description: Learn how to get started with our platform
author: GoGrab Team
lastUpdated: 2025-01-25
---

After (.mdc):

---
title: Getting Started
description: Learn how to get started with our platform
author: GoGrab Team
lastUpdated: 2025-01-25
type: mdc
interactive: true
status: published
difficulty: beginner
estimatedReadTime: 10
toc: true
searchable: true
breadcrumbs: true
sidebar: true

# UI configuration
ui:
  showMetadata: true
  enableInteraction: true
  compactMode: false

# Performance configuration
performance:
  lazyLoad: true
  preload: false
  cacheStrategy: normal
---

Step 2: Content Enhancement

2.1 Add Interactive Components

Code Examples:

<!-- Before: Static code block -->
```typescript
export class ExampleComponent {
  @Input() title = 'Hello World';
}

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


**Live Demos:**
```markdown
<!-- Add interactive demos -->
<mdc:interactive-demo
  component="ButtonComponent"
  :props='{"variant": "primary", "size": "large"}'>

  Try clicking this interactive button!

</mdc:interactive-demo>

Diagrams:

<!-- Add visual diagrams -->
<mdc:diagram
  type="flowchart"
  ai-prompt="Create a flowchart showing the setup process"
  theme="modern">
</mdc:diagram>

2.2 Enhance with AI Features

<!-- Add AI-generated content sections -->
<mdc:ai-content
  prompt="Explain the benefits of this approach"
  confidence="0.95"
  review-status="approved">

  AI-generated insights and explanations.

</mdc:ai-content>

Step 3: Testing and Validation

3.1 Component Testing

3.2 Content Validation

3.3 Performance Testing

Step 4: Deployment and Monitoring

4.1 Deploy Changes

4.2 Monitor Performance

🛠️ Migration Tools and Automation

Automated Migration Script

Create a script to automate basic migration tasks:

// migrate-to-mdc.js
const fs = require('fs');
const path = require('path');

function migrateMarkdownToMDC(filePath) {
  const content = fs.readFileSync(filePath, 'utf8');

  // Add MDC frontmatter
  const mdcContent = addMDCFrontmatter(content);

  // Convert code blocks to interactive components
  const enhancedContent = convertCodeBlocks(mdcContent);

  // Save as .mdc file
  const newPath = filePath.replace('.md', '.mdc');
  fs.writeFileSync(newPath, enhancedContent);

  console.log(`Migrated: ${filePath} -> ${newPath}`);
}

function addMDCFrontmatter(content) {
  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);

  if (frontmatterMatch) {
    const existingFrontmatter = frontmatterMatch[1];
    const body = frontmatterMatch[2];

    // Add MDC-specific fields
    const mdcFrontmatter = addMDCFields(existingFrontmatter);

    return `---\n${mdcFrontmatter}\n---\n${body}`;
  } else {
    // Add basic MDC frontmatter
    const basicFrontmatter = `title: "Document Title"
type: mdc
interactive: true
status: published
toc: true
searchable: true`;

    return `---\n${basicFrontmatter}\n---\n\n${content}`;
  }
}

function convertCodeBlocks(content) {
  // Convert ```language blocks to mdc:code-block components
  return content.replace(/```(\w+)\n([\s\S]*?)```/g,
    '<mdc:code-block language="$1" interactive="true">\n$2\n</mdc:code-block>');
}

Manual Migration Checklist

For each file, verify:

🎨 Content Enhancement Strategies

1. Interactive Code Examples

Before:

Here's how to create a component:

```typescript
@Component({
  selector: 'app-example',
  template: '<h1>{{ title }}</h1>'
})
export class ExampleComponent {
  title = 'Hello World';
}


**After:**
```markdown
Here's how to create a component:

<mdc:code-block
  language="typescript"
  interactive="true"
  theme="vs-dark">
@Component({
  selector: 'app-example',
  template: '<h1>{{ title }}</h1>'
})
export class ExampleComponent {
  title = 'Hello World';
}
</mdc:code-block>

Try editing the code above to see live changes!

2. Live Component Demos

Before:

Our button component supports different variants:

- Primary button
- Secondary button
- Danger button

After:

Our button component supports different variants:

<mdc:interactive-demo
  component="ButtonShowcase"
  :props='{"showVariants": true}'>

  Try different button variants and see them in action!

</mdc:interactive-demo>

3. Visual Diagrams

Before:

The system architecture follows this flow:

1. User makes request
2. API processes request
3. Database stores data
4. Response sent to user

After:

The system architecture follows this flow:

<mdc:diagram
  type="flowchart"
  ai-prompt="Create a flowchart showing the system architecture flow"
  theme="modern"
  interactive="true">
</mdc:diagram>

4. AI-Enhanced Content

Before:

This approach provides several benefits:
- Better performance
- Improved maintainability
- Enhanced user experience

After:

<mdc:ai-content
  prompt="Explain the benefits of this architectural approach"
  confidence="0.92"
  review-status="approved">

  This approach provides several key benefits that make it ideal for modern applications.

</mdc:ai-content>

🚨 Common Migration Issues

Issue 1: Frontmatter Parsing Errors

Problem: YAML frontmatter syntax errors Solution: Validate YAML syntax and ensure proper indentation

# Correct
ui:
  showMetadata: true
  enableInteraction: true

# Incorrect
ui:
showMetadata: true
enableInteraction: true

Issue 2: Component Not Rendering

Problem: Components don't appear in rendered output Solution: Check component syntax and ensure components are registered

<!-- Correct -->
<mdc:code-block language="typescript">
// Code here
</mdc:code-block>

<!-- Incorrect -->
<mdc:code-block language="typescript"
// Code here
</mdc:code-block>

Issue 3: Performance Issues

Problem: Slow page loading with many components Solution: Enable lazy loading and optimize component usage

# In frontmatter
performance:
  lazyLoad: true
  preload: false
  cacheStrategy: normal

Issue 4: Mobile Responsiveness

Problem: Components don't work well on mobile Solution: Test responsive design and adjust component properties

<mdc:interactive-demo
  component="ResponsiveComponent"
  :props='{"mobileOptimized": true}'>
</mdc:interactive-demo>

📊 Migration Metrics

Track These Metrics

Success Criteria

🔄 Rollback Plan

If Migration Fails

  1. Immediate Rollback

    • Revert to previous version
    • Restore original .md files
    • Disable MDC features

  2. Investigation

    • Identify root cause
    • Fix issues
    • Test thoroughly

  3. Re-attempt Migration

    • Apply fixes
    • Test in staging
    • Deploy gradually

🎯 Post-Migration Optimization

1. Performance Tuning

2. Content Updates

3. User Training

🔗 Resources and Support

Documentation

Tools

Support

This migration guide is maintained by the GoGrab Development Team and is updated regularly based on user feedback and new features.