MDC File Format Specification

Complete specification for MDC (Markdown Components) file format, syntax, and features

📋 MDC File Format Specification

MDC (Markdown Components) is an advanced documentation format that extends traditional Markdown with interactive components, AI integration, and structured metadata. This specification defines the complete format and syntax for MDC files.

🎯 Overview

MDC files combine:

📁 File Structure

Basic Structure

---
# Frontmatter (YAML)
title: "Document Title"
description: "Document description"
# ... additional metadata
---

# Markdown Content

Regular markdown content with **formatting** and [links](/other-page).

## Interactive Components

<mdc:component-name prop1="value" prop2="value">
  Optional content
</mdc:component-name>

More markdown content...

File Extensions

🔧 Frontmatter Specification

Core Metadata Fields

Required Fields

title: string              # Document title
type: "mdc"               # Always "mdc" for MDC files

Standard Fields

description: string        # Brief description
author: string            # Content author
lastUpdated: string       # Last update date (ISO format)
version: string           # Document version
language: string          # Content language (en/es)

Content Organization

category: string          # Main category
subcategory: string       # Sub-category
tags: string[]           # Array of tags
order: number            # Display order
status: string           # Content status (draft/published/archived)
difficulty: string       # Difficulty level (beginner/intermediate/advanced)
estimatedReadTime: number # Reading time in minutes

Navigation Control

toc: boolean             # Show table of contents
searchable: boolean      # Include in search
breadcrumbs: boolean     # Show breadcrumbs
sidebar: boolean         # Include in sidebar

MDC-Specific Fields

Component Definitions

components:
  - name: string          # Component name
    version: string       # Component version
    required: boolean     # Whether component is required
    props: object        # Default properties

AI Integration

ai:
  generated: boolean      # AI-generated content flag
  lastUpdate: string     # Last AI update (ISO format)
  prompts: string[]      # AI prompts used
  confidence: number     # AI confidence score (0-1)
  reviewStatus: string   # Review status (pending/approved/needs-revision)
  model:
    name: string         # AI model name
    version: string      # Model version
    provider: string     # AI provider

UI Configuration

ui:
  showMetadata: boolean  # Show metadata panel
  showAIPanel: boolean   # Show AI panel
  enableInteraction: boolean # Enable interactive features
  compactMode: boolean   # Use compact layout
  showComponentInfo: boolean # Show component information
  showDebugInfo: boolean # Show debug information

Performance Settings

performance:
  lazyLoad: boolean      # Enable lazy loading
  preload: boolean       # Enable preloading
  cacheStrategy: string  # Caching strategy (normal/aggressive/minimal)
  enableProfiling: boolean # Enable performance profiling
  maxRenderTime: number  # Maximum render time (ms)
  componentTimeout: number # Component timeout (ms)

Theme Configuration

theme:
  variant: string        # Theme variant (modern/classic/minimal)
  colorScheme: string    # Color scheme (light/dark/adaptive)
  animations: string     # Animation setting (enabled/disabled/reduced)

🧩 Component Syntax

Basic Component Syntax

<mdc:component-name prop1="value" prop2="value">
  Optional content
</mdc:component-name>

Self-Closing Components

<mdc:component-name prop1="value" prop2="value" />

Component with JSON Props

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

  This demonstrates the button component.

</mdc:interactive-demo>

Conditional Components

<mdc:conditional
  condition="user.role === 'developer'"
  fallback="Sign in as a developer to see this content">

  Developer-only content here.

</mdc:conditional>

🎨 Available Component Types

Core Components

Code Display

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



#### Interactive Demos
```markdown
<mdc:interactive-demo
  component="ButtonComponent"
  :props='{"variant": "primary"}'
  sandbox="true"
  height="300px">

  Try interacting with this button!

</mdc:interactive-demo>

Diagrams

<mdc:diagram
  type="flowchart"
  ai-prompt="Create a flowchart showing the process"
  auto-update="true"
  theme="modern">
</mdc:diagram>

AI-Generated Content

<mdc:ai-content
  prompt="Explain the benefits of this approach"
  generated-at="2025-01-25T10:30:00Z"
  confidence="0.95"
  model="claude-3.5-sonnet">

  AI-generated content appears here.

</mdc:ai-content>

Live Data

<mdc:live-data
  source="/api/stats"
  refresh="30s"
  template="stats-display"
  fallback="Loading statistics...">
</mdc:live-data>

Widget Integration

<mdc:widget
  type="theme-preview"
  :config='{"theme": "dark", "components": ["button", "card"]}'>
</mdc:widget>

Advanced Components

Code Playground

<mdc:code-playground
  language="typescript"
  template="angular-component"
  theme="vs-dark"
  interactive="true">

  // Your code here
  import { Component } from '@angular/core';

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

</mdc:code-playground>

Template Components

<mdc:template
  name="custom-template"
  :context='{"title": "Custom Title", "items": ["item1", "item2"]}'>

  <h2>{{ title }}</h2>
  <ul>
    @for (item of items; track item) {
      <li>{{ item }}</li>
    }
  </ul>

</mdc:template>

🔍 Component Properties

Common Properties

Component-Specific Properties

Code Block Properties

Interactive Demo Properties

Diagram Properties

🤖 AI Integration

AI Metadata Structure

ai:
  generated: boolean      # Whether content is AI-generated
  lastUpdate: string     # Last AI update timestamp
  prompts: string[]      # AI prompts used
  confidence: number     # Confidence score (0-1)
  reviewStatus: string   # Review status
  model:
    name: string         # AI model name
    version: string      # Model version
    provider: string     # AI provider
  suggestions:           # AI suggestions for improvement
    - message: string
      type: string
      replacement: string

AI-Enhanced Components

🎨 Styling and Theming

CSS Classes

MDC components automatically receive CSS classes:

Theme Variables

Components inherit theme variables:

.mdc-component {
  background: var(--ux-surface);
  color: var(--ux-on-surface);
  border-radius: var(--ux-border-radius);
}

Responsive Design

Components automatically adapt to screen sizes:

@media (max-width: 768px) {
  .mdc-component {
    /* Mobile-specific styles */
  }
}

🔧 Validation and Error Handling

Component Validation

Error Handling

Validation Rules

validation:
  strictMode: boolean     # Enable strict validation
  allowUnknownComponents: boolean # Allow unknown components
  validateComponents: boolean # Validate component properties
  maxFileSize: number    # Maximum file size (bytes)
  timeout: number        # Processing timeout (ms)

📊 Performance Considerations

Lazy Loading

Caching

Optimization

🔄 Migration from Markdown

Automatic Migration

Migration Steps

  1. Rename: Change .md to .mdc
  2. Add Frontmatter: Add MDC-specific frontmatter
  3. Add Components: Embed interactive components
  4. Test: Validate component rendering
  5. Deploy: Update routing and navigation

Migration Tools

🚀 Best Practices

File Organization

Component Usage

Performance

Accessibility

🔗 Related Resources

This specification is maintained by the GoGrab Development Team and is updated regularly to reflect new features and improvements.