169 lines
5.6 KiB
Markdown
169 lines
5.6 KiB
Markdown
# 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* |