diff --git a/GAMEPLAN_ISSUE_132_instant_markdown.md b/GAMEPLAN_ISSUE_132_instant_markdown.md new file mode 100644 index 00000000..eec380c8 --- /dev/null +++ b/GAMEPLAN_ISSUE_132_instant_markdown.md @@ -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 + + + + {{ title }} + + + + +
+ + + + +``` + +#### 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* \ No newline at end of file diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE_md_prefix.md similarity index 100% rename from MIGRATION_GUIDE.md rename to MIGRATION_GUIDE_md_prefix.md diff --git a/todo/NEXT_SESSION_BRIEFING.md b/history/2025-10-02_next_session_briefing.md similarity index 100% rename from todo/NEXT_SESSION_BRIEFING.md rename to history/2025-10-02_next_session_briefing.md diff --git a/todo/COST_TRACKING_GAMEPLAN.md b/history/COST_TRACKING_GAMEPLAN.md similarity index 100% rename from todo/COST_TRACKING_GAMEPLAN.md rename to history/COST_TRACKING_GAMEPLAN.md diff --git a/todo/COST_TRACKING_ISSUES.md b/history/COST_TRACKING_ISSUES.md similarity index 100% rename from todo/COST_TRACKING_ISSUES.md rename to history/COST_TRACKING_ISSUES.md diff --git a/ISSUE_37_IMPLEMENTATION_SUMMARY.md b/history/ISSUE_37_IMPLEMENTATION_SUMMARY.md similarity index 100% rename from ISSUE_37_IMPLEMENTATION_SUMMARY.md rename to history/ISSUE_37_IMPLEMENTATION_SUMMARY.md