# GAMEPLAN - Issue #132: Instant Markdown JavaScript Client-Side Rendering

## Issue Overview
**Goal**: Generate HTML pages with JavaScript-based client-side markdown rendering
**Requirement**: HTML page with embedded markdown payload that renders in browser on page load

## Implementation Strategy

### Phase 1: Core Architecture Design
1. **HTML Template System**
   - Create base HTML template with markdown payload embedding
   - Include JavaScript markdown parser (marked.js or similar)
   - Design payload embedding strategy (script tags, data attributes, or inline JSON)

2. **CLI Command Implementation**
   - Add new `md-render` command to markdown plugin
   - Parse markdown file and extract front matter
   - Generate complete HTML with embedded content

### Phase 2: JavaScript Integration
1. **Markdown Parser Selection**
   - Evaluate client-side markdown parsers (marked.js, markdown-it, etc.)
   - Choose CDN vs bundled approach
   - Ensure syntax highlighting support if needed

2. **Rendering Engine**
   - Implement JavaScript that runs on page load
   - Handle front matter display (if required)
   - Apply styling and formatting

### Phase 3: Template Customization
1. **Template Options**
   - Basic template with minimal styling
   - Multiple template variants (GitHub style, academic, etc.)
   - Custom CSS injection capability

2. **Configuration Integration**
   - Use existing config system for defaults
   - Template selection via CLI flags
   - Output directory configuration

## Technical Implementation Plan

### Step 1: Command Structure
```bash
markitect md-render input.md --output rendered.html --template basic
markitect md-render input.md --template github --css custom.css
```

### Step 2: File Architecture
```
markitect/
├── templates/
│   ├── basic.html          # Base template
│   ├── github.html         # GitHub-style template
│   └── academic.html       # Academic paper style
├── plugins/builtin/
│   └── markdown_commands.py # Add md-render command
└── assets/
    ├── marked.min.js       # Bundled markdown parser
    └── styles/
        ├── basic.css
        └── github.css
```

### Step 3: Implementation Components

#### 1. HTML Template Structure
```html
<!DOCTYPE html>
<html>
<head>
    <title>{{ title }}</title>
    <meta charset="utf-8">
    <style>{{ css_content }}</style>
</head>
<body>
    <div id="markdown-content"></div>
    <script src="{{ markdown_js_url }}"></script>
    <script>
        // Embedded markdown payload
        const markdownContent = {{ markdown_json }};
        const frontMatter = {{ front_matter_json }};

        // Render on page load
        document.addEventListener('DOMContentLoaded', function() {
            document.getElementById('markdown-content').innerHTML =
                marked.parse(markdownContent);
        });
    </script>
</body>
</html>
```

#### 2. CLI Command Implementation
- Extend `MarkdownCommandsPlugin` with `md-render` command
- Read markdown file and parse front matter
- Load HTML template and substitute variables
- Write output HTML file

#### 3. Template Engine
- Simple template substitution system
- Support for CSS injection
- Front matter display options

## Development Workflow (TDD8 Ready)

### Test Scenarios (7+ tests)
1. **Basic Rendering Test**: Convert simple markdown to HTML
2. **Front Matter Test**: Handle YAML front matter properly
3. **Template Selection Test**: Use different templates
4. **Custom CSS Test**: Inject custom stylesheets
5. **Large File Test**: Handle substantial markdown files
6. **Special Characters Test**: Unicode and special markdown syntax
7. **Integration Test**: End-to-end CLI command execution

### Implementation Steps
1. **ISSUE**: Analyze requirements and design architecture
2. **TEST**: Create comprehensive test suite for rendering
3. **RED**: Implement failing tests for md-render functionality
4. **GREEN**: Build minimal working renderer
5. **REFACTOR**: Clean up template system and add features
6. **DOCUMENT**: Add docstrings and usage examples
7. **REFINE**: Test full integration and performance
8. **PUBLISH**: Update CLI help and documentation

## Technical Considerations

### Dependencies
- **JavaScript Library**: marked.js (lightweight, fast)
- **Template System**: Simple string substitution (no new dependencies)
- **File I/O**: Use existing file handling patterns

### Security Considerations
- Sanitize markdown content to prevent XSS
- Validate template paths to prevent directory traversal
- Consider Content Security Policy headers

### Performance Considerations
- Bundle vs CDN approach for JavaScript library
- Template caching for repeated operations
- Large file handling and memory usage

### Integration Points
- Extend existing `MarkdownCommandsPlugin`
- Use established configuration management
- Follow existing CLI patterns and error handling
- Integrate with database for metadata if needed

## Success Criteria
- ✅ Generate HTML files with embedded markdown
- ✅ JavaScript renders markdown on page load
- ✅ Support multiple template styles
- ✅ Handle front matter appropriately
- ✅ CLI command follows project conventions
- ✅ Comprehensive test coverage (7+ tests)
- ✅ Documentation and help text complete

## Future Enhancements (Post-MVP)
- Live preview mode with file watching
- Multiple output formats (PDF generation)
- Syntax highlighting for code blocks
- Table of contents generation
- Search functionality within rendered pages
- Batch processing of multiple files

---
*Generated for Issue #132 - Instant Markdown JavaScript Client-Side Rendering*
*Ready for TDD8 workflow implementation*