MarcinDudekDev HTML Report Generation
When to Use
- Task completions with file changes
- Research results and analysis
- Audits and quality checks
- Error/blocker reports requiring user action
- Comparisons (tools, approaches, options)
- Any output exceeding ~10 lines
When NOT to Use
- Short answers, yes/no, status updates
- Quick confirmations (<10 lines)
Report Types
task-completion
Sections: Summary, Changes Made (files list), Verification Results, Next Steps
research
Sections: Key Findings, Detailed Analysis, Recommendations, Sources
audit
Sections: Overall Score/Grade, Pass/Fail Table, Detailed Findings, Recommendations
error-blocker
Sections: What's Blocked, Root Cause Analysis, What User Needs To Do, Workarounds
comparison
Sections: Options Overview Table (with pros/cons), Detailed Analysis, Recommendation
Workflow
- Generate HTML content using the template below
- Get project name:
tmux display-message -p '#S' 2>/dev/null || basename "$PWD" - Get target path:
report --path --project "{name}" --title "{title}" --type {type} - Write the HTML file to that path
- Open it:
report --open "{filepath}" - Print ONE line to terminal:
Report: {title} -> {filepath}
HTML Template
<!DOCTYPE html>
<html lang="en" data-theme="dark">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>REPORT_TITLE</title>
<meta name="report-type" content="REPORT_TYPE">
<meta name="report-project" content="PROJECT_NAME">
<meta name="report-date" content="YYYY-MM-DD">
<script type="application/json" id="report-meta">
{"title": "REPORT_TITLE", "type": "REPORT_TYPE", "project": "PROJECT_NAME", "date": "YYYY-MM-DD"}
</script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
<style>
:root { --pico-font-size: 15px; }
body { max-width: 900px; margin: 0 auto; padding: 2rem 1rem; }
.report-header { border-bottom: 1px solid var(--pico-muted-border-color); padding-bottom: 1rem; margin-bottom: 2rem; }
.report-header h1 { margin-bottom: 0.3rem; }
.meta { font-size: 0.85em; opacity: 0.6; }
.meta span { margin-right: 1.5em; }
.badge { display: inline-block; padding: 0.15em 0.5em; border-radius: 4px; font-size: 0.8em; font-weight: 600; }
.badge-success { background: #065f46; color: #6ee7b7; }
.badge-warning { background: #78350f; color: #fcd34d; }
.badge-error { background: #7f1d1d; color: #fca5a5; }
.badge-info { background: #1e3a5f; color: #93c5fd; }
table { width: 100%; }
table td, table th { padding: 0.5rem 0.75rem; }
.score { font-size: 2em; font-weight: 700; }
.pass { color: #6ee7b7; }
.fail { color: #fca5a5; }
.warn { color: #fcd34d; }
pre { font-size: 0.85em; overflow-x: auto; }
.section { margin-bottom: 2rem; }
details summary { cursor: pointer; font-weight: 600; }
details { margin-bottom: 1rem; }
</style>
</head>
<body>
<div class="report-header">
<h1>REPORT_TITLE</h1>
<div class="meta">
<span>PROJECT_NAME</span>
<span>YYYY-MM-DD HH:MM</span>
<span class="badge badge-info">REPORT_TYPE</span>
</div>
</div>
<main>
<!-- REPORT CONTENT HERE -->
</main>
<footer style="margin-top:3rem;padding-top:1rem;border-top:1px solid var(--pico-muted-border-color);font-size:0.8em;opacity:0.4">
Generated by Claude Code
</footer>
</body>
</html>
Content Patterns
Pass/Fail Row (for audit tables)
<tr>
<td>Check Name</td>
<td><span class="pass">✓ Pass</span></td>
<td>Details about what was checked</td>
</tr>
File Change Row (for task-completion)
<tr>
<td><code>path/to/file.py</code></td>
<td>Modified</td>
<td>Brief description of change</td>
</tr>
Comparison Cell
<td>
<strong>Option Name</strong><br>
<span class="pass">+ Pro point</span><br>
<span class="fail">- Con point</span>
</td>
Images in Reports
- NEVER embed base64-encoded images in report HTML
- When including screenshots or images:
- Save the image file in the same directory as the report HTML
- Reference with relative path:
<img src="screenshot.webp" alt="description">
- Image filenames should be descriptive:
homepage-hero.webp,error-state.webp, etc.
Important
- Reports are SELF-CONTAINED — all CSS is inline or from CDN
- Always include the
<script id="report-meta">JSON block for indexing - Always include both
<meta name="report-*">tags AND the JSON block - Use semantic HTML:
<section>,<table>,<details>,<pre><code> - Keep reports focused — one topic per report