markdown-html-orchestrator

---
name: markdown-html-orchestrator
description: Use when a user wants long markdown (specs, reports, PR reviews with diffs, or slide decks) turned into a single branded HTML document or deck.
category: Formatting
version: 1.0.0
tools: []
---

# Markdown-to-HTML Conversion — Format Router

Long-form markdown — specs, reports, code reviews with diffs, or slide decks — loses density and interaction past roughly 100 lines. Below that threshold markdown alone is better; above it, converting to a single self-contained HTML document or deck restores hierarchy, a table of contents, code-copy affordances, and light interactivity. Classify the document's type first, confirm the user's brand once per conversation (see the design-system skill), then produce the right layout.

## Pre-flight checks (refuse if either fails)
1. **Under ~100 lines.** If the pasted/described markdown is short, say markdown already works well and skip conversion.
2. **No brand captured yet.** If this is the first branded output in the conversation, run design-system onboarding first — output without it looks generic.

## Classifying the document (two-signal method)
Score each candidate type using a description hint (2 points, from what the user calls the document) plus content signals (1 point each, from the markdown's structure). Silently pick the winner when its score is at least 3 AND either the runner-up scored 0 or the winner scored at least twice the runner-up; otherwise ask one clarifying question with a recommended answer.

| Type | Description hints | Content signals |
|---|---|---|
| **Document** (report/spec/RFC/explainer) | called a report, spec, RFC, analysis, explainer | table of contents, `#`/`##` heading structure, markdown tables, `> [!NOTE]`/`[!TIP]`/`[!IMPORTANT]` callouts |
| **Review** (PR writeup/code review) | called a review, PR writeup, diff | fenced ```diff``` blocks, `+++`/`---`/`@@` diff markers, `> [!BLOCKER]`/`[!MAJOR]`/`[!MINOR]`/`[!NIT]` callouts, "LGTM"/"nit:"/"blocker:" language |
| **Slides** (deck/talk/presentation) | called a deck, slides, talk, presentation | `---` horizontal-rule slide boundaries (3+), `<!-- notes: -->` speaker-note comments, 5+ top-level headings with a short median gap between them |

## Workflow
1. Confirm the user's brand is set (design-system).
2. Classify using the table above; ask one question if the signal is ambiguous.
3. Build the HTML as a single self-contained document — inline all styling using the confirmed brand tokens, no external files, no build step. Use vanilla JS only for interactivity (collapsibles, scrollspy, arrow-key slide navigation); avoid frameworks.
4. Return the complete HTML in a chat code block the user can save and open directly, plus a short summary: input length, document type chosen, design style applied, and the top interactive features included.

## What each type should include
- **Document** — sticky table of contents, collapsible sections, in-page search where practical, copyable code blocks, scroll-linked TOC highlighting.
- **Review** — two-column or inline diff rendering, severity-tagged margin notes (blocker/major/minor/nit), jump navigation between comments.
- **Slides** — one screen per `---`-delimited section, arrow-key navigation, a presenter/notes view, and print-friendly styling so the user can print to PDF from their browser.

## Forcing questions (ask one at a time, each with a recommendation)
1. **Is the reader skimming, deciding, or presenting?** Name the purpose first — density follows from it (Edward Tufte, *Visual Display of Quantitative Information*).
2. **Is the input at least ~100 lines?** Below that, recommend keeping it as markdown.
3. **Has the brand been captured this conversation?** If not, run onboarding first.
4. **Confident on document type, or ambiguous?** Silent-route only when the scoring rule above clears the threshold; otherwise ask.

## Why HTML over markdown at length
Markdown is flat — every heading level, callout, and code block competes for the same visual weight once a document runs long. A single-file HTML document can add a persistent table of contents so the reader always knows where they are, collapsible sections so dense material doesn't have to be read linearly, syntax-aware code blocks with a one-click copy affordance, and (for reviews) a two-column layout that keeps the original and the diff side by side instead of interleaved. None of that requires a server or a build step — it's still one file the user can open directly in a browser or attach to an email.

## Non-goals
Not a landing-page generator. Not a multi-file or static site — always a single returned document, never an extracted CSS file or an asset directory. Not a PDF generator — slide decks rely on the browser's print function (`@media print` styling) rather than a PDF export step. Not a live-reload pipeline — each conversion is one-shot; if the source markdown changes, re-run the conversion.

## Anti-patterns
- Converting markdown under ~100 lines — say so and keep it as markdown.
- Producing HTML before the brand is confirmed — it will look unbranded.
- Silently chaining conversions (e.g., turning a doc into slides unasked) — finish one, then ask before chaining.
- Reaching for a JS framework (React, Vue, Svelte) — vanilla JS plus `IntersectionObserver` keeps the output a single portable file; a syntax-highlighting library is the one acceptable exception.
- Overwriting a document the user already has open elsewhere — when in doubt, ask before replacing prior output rather than silently regenerating it.

## References
An essay on agent-generated HTML replacing long-form markdown output for specs, reviews, and decks (Thariq Shihipar, 2026); Edward Tufte, *Visual Display of Quantitative Information*, for the underlying information-density argument; WCAG 2.2 §1.4.3 for the text-contrast floor carried over from the design-system skill.