chore: some cleanup and houskeeping
This commit is contained in:
169
GAMEPLAN_ISSUE_132_instant_markdown.md
Normal file
169
GAMEPLAN_ISSUE_132_instant_markdown.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user