markitect-main/docs/PLUGIN_SYSTEM.md

Markitect Plugin System Documentation

Overview

The Markitect plugin system provides a modular architecture for extending rendering capabilities with independent JavaScript UI components. This system enables JavaScript-first development while maintaining clean integration with the Python ecosystem.

Architecture

Core Components

1. RenderingEnginePlugin: Base class for UI rendering engines
2. RenderingConfig: Asset management and deployment configuration
3. RenderingEngineManager: Plugin discovery and lifecycle management
4. PluginManager: Integration with existing Markitect plugin system

Key Features

• Clean Separation: JSON-based configuration interface (Python ↔ JavaScript)
• Independent Development: JavaScript components work standalone
• Asset Management: Configurable deployment strategies
• Multiple Engines: Support for different UI frameworks
• Fallback Support: Graceful degradation to standard rendering

Plugin Development

Creating a Rendering Engine Plugin

1. Extend RenderingEnginePlugin:

from markitect.plugins.rendering import RenderingEnginePlugin, RenderingConfig
from markitect.plugins.base import PluginMetadata, PluginType

class MyUIEngine(RenderingEnginePlugin):
    def __init__(self):
        super().__init__()
        self._metadata = PluginMetadata(
            name="my-ui-engine",
            version="1.0.0",
            description="Custom UI rendering engine",
            author="Your Name",
            plugin_type=PluginType.RENDERING
        )

    @property
    def metadata(self) -> PluginMetadata:
        return self._metadata

    def get_supported_modes(self) -> List[str]:
        return ["edit", "view"]

    def get_required_assets(self) -> Dict[str, List[str]]:
        return {
            "js": ["static/js/main.js"],
            "css": ["static/css/style.css"]
        }

    def render_document(self, content: str, mode: str, config: RenderingConfig) -> str:
        # Your rendering logic here
        return html_output

2. Directory Structure:

my-ui-engine/
├── static/
│   ├── js/           # JavaScript components
│   └── css/          # Stylesheets
├── templates/        # HTML templates
├── images/           # Icons and images
├── test-documents/   # Sample markdown files
├── package.json      # Node.js configuration
└── README.md         # Plugin documentation

3. Asset Management:

Assets are automatically deployed based on configuration:

• Development: Served from plugin source directory
• Production: Copied to _markitect/plugins/{plugin-name}/

TestDrive JSUI Plugin

Overview

The TestDrive JSUI plugin demonstrates the plugin architecture with a complete JavaScript UI for markdown editing.

Features

• Modular Components: Clean separation of UI components
• Compass Positioning: NW, NE, E, SE control panel layout
• Section Management: Click-to-edit markdown sections
• Debug System: Built-in debugging and logging
• Asset Pipeline: Configurable asset deployment

Directory Structure

testdrive-jsui/
├── static/js/
│   ├── core/             # Core systems
│   │   ├── debug-system.js
│   │   └── section-manager.js
│   ├── components/       # UI components
│   │   ├── debug-panel.js
│   │   ├── document-controls.js
│   │   └── dom-renderer.js
│   ├── controls/         # Control panels
│   │   ├── control-base.js
│   │   ├── contents-control.js   # Northwest
│   │   ├── status-control.js     # East
│   │   ├── debug-control.js      # Southeast
│   │   └── edit-control.js       # Northeast
│   ├── config-loader.js  # Configuration interface
│   └── main-updated.js   # Application entry point
├── static/css/           # Stylesheets (future)
├── images/               # Icons and images (future)
├── templates/
│   └── index.html        # Main HTML template
├── test-documents/
│   └── sample.md         # Test content
├── test.html             # Standalone development
├── package.json          # Node.js configuration
└── README.md             # Plugin documentation

JavaScript Architecture

• Configuration Interface: Clean JSON data transfer via markitect-config script element
• Modular Components: Each component has single responsibility
• Event System: Pub/sub for component communication
• Control System: Abstract base class for UI controls
• Compass Positioning: Consistent control panel layout

CLI Integration

Command Line Usage

# Use default engine (testdrive-jsui for edit/insert, standard for view)
markitect md-render --edit document.md

# Specify engine explicitly
markitect md-render --engine testdrive-jsui --edit document.md

# Use standard engine
markitect md-render --engine standard --edit document.md

# View available engines
markitect md-render --help

Engine Selection Logic

1. Default Selection:

   • Edit/Insert modes: testdrive-jsui
   • View mode: standard

2. Explicit Selection: Use --engine parameter

3. Fallback Strategy:

   • Engine not found → fallback to standard
   • Mode not supported → fallback to standard
   • Plugin error → fallback to standard

Integration Points

The CLI integrates with the plugin system through:

# Engine discovery
plugin_manager = PluginManager()
rendering_manager = RenderingEngineManager(plugin_manager)

# Engine selection
engine = rendering_manager.get_engine(engine_name)

# Configuration
config = RenderingConfig(
    asset_base_url="_markitect",
    development_mode=False,
    output_directory=output_path.parent
)

# Rendering
html_content = engine.render_document(content, mode, config)

Development Workflows

Standalone JavaScript Development

1. Setup:

   cd testdrive-jsui
   python -m http.server 8080
   

2. Development:

   • Edit JavaScript files in static/js/
   • Refresh browser to see changes
   • Use test.html for testing
   • Browser DevTools for debugging

3. Benefits:

   • No Python environment required
   • Fast iteration cycle
   • Standard web development tools
   • Hot reloading

Integrated Development

1. Plugin Testing:

   python demo_plugin_integration.py
   

2. CLI Testing:

   markitect md-render --engine testdrive-jsui --edit test.md
   

3. Integration Verification:

   python test_complete_integration.py
   

Asset Management

Development Mode

config = RenderingConfig(
    asset_base_url=".",
    development_mode=True,
    plugin_source_dirs={"testdrive-jsui": Path("testdrive-jsui")}
)

# Assets served as: file://testdrive-jsui/static/js/main.js

Production Mode

config = RenderingConfig(
    asset_base_url="_markitect",
    development_mode=False,
    output_directory=Path("/output")
)

# Assets served as: _markitect/plugins/testdrive-jsui/static/js/main.js

Asset Types

• js: JavaScript files
• css: Stylesheets
• images: Icons, graphics
• external: CDN resources

Deployment Strategy

1. Assets Copying: Plugin assets copied to _markitect/plugins/{name}/
2. URL Generation: Automatic URL generation for templates
3. Cache Management: Asset versioning and cache control
4. Error Handling: Fallback for missing assets

Asset Deployment Process

When using CLI with plugin engines, assets are automatically deployed:

# Assets are deployed to output directory when using plugin engines
markitect md-render --edit document.md --output /path/to/output.html

# Output structure:
# /path/to/
# ├── output.html
# └── _markitect/
#     └── plugins/
#         └── testdrive-jsui/
#             ├── static/
#             │   ├── js/          # 12 JavaScript files
#             │   └── css/         # 3 CSS files
#             └── images/          # 3 image files

The deployment process:

1. Plugin Discovery: Engine identified (default: testdrive-jsui for edit mode)
2. Asset Analysis: Required assets determined from get_required_assets()
3. Source Resolution: Plugin source directory located
4. File Copying: Assets copied with directory structure preservation
5. URL Generation: HTML references generated with correct paths
6. Verification: Asset accessibility validated

Example output:

🎯 Using rendering engine: testdrive-jsui (supports: edit, view)
📦 Deploying assets for engine 'testdrive-jsui'...
📄 Deployed 18 asset files
   js: 12 files
   css: 3 files
   images: 3 files
✅ Rendered with INTERACTIVE editing mode to: output.html

Configuration Interface

Python → JavaScript Data Transfer

All dynamic data passes through a clean JSON interface:

<script id="markitect-config" type="application/json">
{
  "markdownContent": "# Document content...",
  "mode": "edit",
  "theme": "github",
  "keyboardShortcuts": true,
  "originalFilename": "document.md",
  "version": "Markitect v0.8.1"
}
</script>

JavaScript Configuration Loading

// Clean configuration loading
class MarkitectConfig {
    constructor() {
        this.loadConfig();
    }

    loadConfig() {
        const configElement = document.getElementById('markitect-config');
        this.config = JSON.parse(configElement.textContent);
    }
}

Benefits

• No String Interpolation: Prevents template literal escaping issues
• Type Safety: JSON validation and error handling
• Clean Separation: No JavaScript code in Python strings
• Debuggable: Easy to inspect configuration in browser

Testing

Plugin Testing

# Basic plugin discovery
python test_plugin_discovery.py

# CLI integration logic
python test_cli_simple.py

# Complete scenario testing
python test_complete_integration.py

# Full integration demo
python demo_plugin_integration.py

Browser Testing

1. Standalone: Open testdrive-jsui/test.html
2. Generated: Open CLI-generated HTML files
3. DevTools: Use browser debugging tools
4. Console: Check for JavaScript errors

Integration Testing

• Unit Tests: Individual component testing
• Integration Tests: Component interaction testing
• E2E Tests: Full workflow testing
• Regression Tests: Ensure stability across changes

Extension Points

Adding New Engines

1. Create new plugin extending RenderingEnginePlugin
2. Implement required methods (get_supported_modes, render_document, etc.)
3. Register in RenderingEngineManager._register_builtin_rendering_engines()
4. Test with CLI integration

Adding New Modes

1. Add mode to engine's get_supported_modes()
2. Update render_document() to handle new mode
3. Test mode validation and rendering
4. Update CLI integration if needed

Adding New Asset Types

1. Update get_required_assets() return format
2. Modify asset deployment logic in RenderingConfig
3. Update template system to handle new asset types
4. Test asset URL generation

Best Practices

Plugin Development

• Single Responsibility: Each component has one clear purpose
• Clean Interfaces: Well-defined APIs between components
• Error Handling: Graceful degradation on failures
• Documentation: Clear README and code comments

JavaScript Development

• Modular Architecture: Avoid monolithic JavaScript files
• Event-Driven: Use pub/sub for component communication
• Configuration-Driven: Avoid hardcoded values
• Browser Compatibility: Test across different browsers

Asset Management

• Relative Paths: Use relative paths in asset definitions
• Versioning: Include version info for cache management
• Optimization: Minimize asset size for production
• CDN Integration: Use CDN for external dependencies

Testing Strategy

• Automated Testing: Comprehensive test coverage
• Manual Testing: User workflow validation
• Cross-Platform: Test on different environments
• Performance Testing: Monitor rendering performance

Troubleshooting

Common Issues

1. Plugin Not Found:

   • Check plugin registration in _register_builtin_rendering_engines()
   • Verify plugin class inheritance from RenderingEnginePlugin
   • Check import paths and module availability

2. Asset Loading Errors:

   • Verify asset paths in get_required_assets()
   • Check file permissions and existence
   • Validate URL generation in different modes

3. Configuration Errors:

   • Check JSON syntax in configuration
   • Verify configuration element ID (markitect-config)
   • Test configuration loading in JavaScript

4. Rendering Failures:

   • Check template file existence and permissions
   • Verify template placeholder replacement
   • Test with minimal content for debugging

Debug Techniques

• Console Logging: Use browser console for debugging
• Debug Panel: TestDrive JSUI includes debug information
• Verbose Mode: Use CLI --verbose flag for detailed output
• Test Scripts: Run individual test scripts for isolation

Future Enhancements

Planned Features

• Plugin Package Manager: npm-like plugin distribution
• Theme System Integration: Plugin-aware theme system
• Performance Monitoring: Built-in performance tracking
• Hot Reloading: Automatic reload on file changes

Extension Opportunities

• React Integration: React-based rendering engine
• Vue Integration: Vue.js-based rendering engine
• TypeScript Support: TypeScript plugin development
• Testing Framework: Automated JavaScript testing

Community

• Plugin Registry: Central repository for community plugins
• Documentation: Expanded examples and tutorials
• Templates: Starter templates for new plugins
• Best Practices: Community guidelines and patterns

---

This plugin system enables JavaScript-first development while maintaining clean integration with the MarkiTect Python ecosystem, providing the best of both worlds for UI development and backend processing.