Files

tegwick 2f878a7138 chore: commit examples and some cleanup

2025-10-08 10:14:51 +02:00

5.6 KiB

Raw Blame History

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

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)
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

Markdown Parser Selection
- Evaluate client-side markdown parsers (marked.js, markdown-it, etc.)
- Choose CDN vs bundled approach
- Ensure syntax highlighting support if needed
Rendering Engine
- Implement JavaScript that runs on page load
- Handle front matter display (if required)
- Apply styling and formatting

Phase 3: Template Customization

Template Options
- Basic template with minimal styling
- Multiple template variants (GitHub style, academic, etc.)
- Custom CSS injection capability
Configuration Integration
- Use existing config system for defaults
- Template selection via CLI flags
- Output directory configuration

Technical Implementation Plan

Step 1: Command Structure

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

<!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)

Basic Rendering Test: Convert simple markdown to HTML
Front Matter Test: Handle YAML front matter properly
Template Selection Test: Use different templates
Custom CSS Test: Inject custom stylesheets
Large File Test: Handle substantial markdown files
Special Characters Test: Unicode and special markdown syntax
Integration Test: End-to-end CLI command execution

Implementation Steps

ISSUE: Analyze requirements and design architecture
TEST: Create comprehensive test suite for rendering
RED: Implement failing tests for md-render functionality
GREEN: Build minimal working renderer
REFACTOR: Clean up template system and add features
DOCUMENT: Add docstrings and usage examples
REFINE: Test full integration and performance
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

5.6 KiB Raw Blame History