mk:preview
Generates visual artifacts — markdown and self-contained HTML — for explaining code, drawing diagrams, building slide decks, visualizing diffs, and rendering plans for review.
No live server. No Python. Pure markdown + HTML + bash file operations. Output writes to tasks/plans/{active-plan}/visuals/ when an active plan exists; otherwise falls back to tasks/visuals/.
When to Use
- A reader needs to understand an unfamiliar code path, protocol, or architecture
- A diagram (flowchart, sequence, ER) would communicate the topology faster than prose
- Step-by-step content benefits from slides over a single long page
- A pre-PR diff review needs visual KPIs, file map, and change cards
- An active plan needs an HTML render for a meeting (display only, not critique)
- Stakeholders prefer a self-contained HTML page they can open in a browser without a server
Default (No Arguments)
If invoked with no arguments, present available operations via AskUserQuestion. Header: "Preview Operation". Question: "What would you like to do?".
| Operation | Description |
|---|---|
--explain | Markdown visual explanation (ASCII + Mermaid + prose) |
--diagram | Markdown diagram (ASCII + Mermaid) |
--slides | Markdown presentation slides |
--ascii | Terminal-friendly ASCII diagram only |
--html --explain | Self-contained HTML explanation, opens in browser |
--html --diagram | HTML diagram with zoom/pan controls |
--html --slides | Magazine-quality HTML slide deck |
--html --diff | HTML diff visualization (KPI grid + file map + cards) |
--html --plan-review | HTML render of a plan for review meetings |
Recommended default: --explain or --html --explain.
Usage
Markdown Generation
/mk:preview --explain <topic>— visual explanation (ASCII + Mermaid + concepts)/mk:preview --diagram <topic>— focused diagram (ASCII + Mermaid)/mk:preview --slides <topic>— presentation slides (one concept per slide)/mk:preview --ascii <topic>— ASCII-only diagram (terminal-friendly)
HTML Generation
/mk:preview --html --explain <topic>— self-contained HTML explanation/mk:preview --html --diagram <topic>— HTML diagram with zoom/pan/mk:preview --html --slides <topic>— magazine-quality slide deck
Analytical Modes
/mk:preview --html --diff [ref]— visualize a git diff. Defaultref=main. Accepts branch, commit, range, PR number./mk:preview --html --plan-review [plan-file]— render a plan as HTML. Default = active plan fromsession-state/active-plan.
--ascii does not combine with --html (terminal-only by design).
Argument Resolution
Priority order:
--htmlflag detected → set HTML output mode- Generation flag detected (
--explain,--diagram,--slides,--ascii) → loadreferences/generation-modes.md - HTML-only flags (
--diff,--plan-review) → imply--html; loadreferences/analytical-modes.md - Topic missing → ask user via
AskUserQuestion - Topic present → continue
Topic-to-slug:
- Lowercase the topic
- Replace spaces and special chars with hyphens
- Remove non-alphanumeric except hyphens
- Collapse multiple hyphens to single
- Trim leading/trailing hyphens
- Truncate at 80 chars on a word boundary
Title placeholder {topic} uses the original input in title case, not the slug.
Multiple flags: if more than one generation flag is supplied, use the first; the rest become part of the topic string.
Output Path Lifecycle
session-state/active-plan exists?
yes → value is absolute path?
yes → {value}/visuals/
no → tasks/plans/{value}/visuals/ (treated as slug)
no → tasks/visuals/
Detail and the bash detection snippet live in references/generation-modes.md → "Step 1 — Resolve output path". The fallback path is logged on stderr (warn:) so silent path mismatches surface immediately.
Error Handling
| Error | Action |
|---|---|
| Topic empty after sanitization | Ask user for an alphanumeric topic |
| Flag without topic | Ask user for the topic string |
| File write failure | Report the error; suggest checking disk space and permissions |
| Output path already exists | Overwrite without prompting |
--diff outside a git repo | Explain: "No git repository detected" |
--diff with PR number, no gh | Suggest installing gh from https://cli.github.com/ |
--plan-review with no plan file or active plan | Ask user for the plan path |
--html --ascii combination | Reject; suggest --html --diagram instead |
| Active-plan path absolute but missing | Log warning; fall back to tasks/visuals/ |
| Active-plan slug with no matching dir | Log warning; fall back to tasks/visuals/ |
Reference Loading
Every mode reads its references BEFORE writing the output file.
| Mode | Always reads | Mode-specific |
|---|---|---|
--explain | references/generation-modes.md, references/mermaid-essentials.md | — |
--diagram | references/generation-modes.md, references/mermaid-essentials.md | — |
--slides | references/generation-modes.md, references/mermaid-essentials.md | — |
--ascii | references/generation-modes.md | — |
--html --explain | references/html-design-rules.md, mk:frontend-design/references/anti-slop-directives.md | template assets/architecture.html |
--html --diagram | references/html-design-rules.md, references/mermaid-essentials.md, mk:frontend-design/references/anti-slop-directives.md | template assets/mermaid-flowchart.html |
--html --slides | references/html-design-rules.md, mk:frontend-design/references/anti-slop-directives.md | template assets/slide-deck.html |
--html --diff | references/html-design-rules.md, references/analytical-modes.md, mk:frontend-design/references/anti-slop-directives.md | template assets/data-table.html, assets/architecture.html |
--html --plan-review | `references/html-design-r |