md-review

---
name: md-review
description: Use when formatting code review markdown with diff blocks and severity callouts into 2-column HTML with jump navigation.
category: Formatting
version: 1.0.0
tools: []
---

# md-document — Long-form Markdown to HTML

Convert long-form markdown (specs, plans, RFCs, reports, explainers) into a single-file HTML document with sticky TOC, scrollspy, search filter, code-copy buttons, and design-system-driven brand tokens.

Three stdlib tools pipeline together: markdown parser (md → JSON AST) → html renderer (AST + tokens → HTML) → interactivity injector (HTML + JS behavior).

Output is one `.html` file with the user's 12 derived brand tokens. Externals limited to Google Fonts CSS and Prism.js CDN.

## What Gets Rendered

CommonMark subset with GFM extensions, sufficient for agent-generated artifacts:
- Headings H1-H6 (every H2+ gets an anchor id and TOC entry)
- Paragraphs with inline **bold** / *italic* / `code` / [links](url) / ![images](url)
- Fenced code blocks (` ```python `) with Prism.js highlighting on demand
- GFM tables with per-column alignment
- GFM callouts (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`)
- Blockquotes, ordered + unordered lists (single-level), horizontal rules

Out of scope: nested lists, HTML inlines, footnotes, definition lists, task list checkboxes, reference-style links.

## Rendering

Deterministic and reproducible across all design-system onboarding states. Supports all four interactive features: TOC, search, scrollspy, code-copy buttons.

## Hard Rules

1. Refuses input < 100 lines (markdown wins below the threshold).
2. Refuses without design-system onboarding.
3. Single-file output. All CSS + JS inline. Only externals are Google Fonts and Prism CDN.
4. Customization must change behavior. `design_style=editorial` produces 720px-wide layout with 1.75 line-height; `playful` rounds callouts and adds shadow; `technical` is dense with 0.875rem code.
5. WCAG-compliant tokens. Body text ≥ 4.5:1 contrast, links iteratively walked to 4.5:1.
6. Idempotent injection. Re-injecting interactivity is a no-op (marker check).

## Interactive Features

- Sticky-sidebar TOC for > 800 words / 4+ H2s
- Search filter for headings  
- Smooth scroll on anchor clicks
- Scrollspy highlighting of current section
- Code copy buttons

## Distinct From

- **`md-review`** — renders diff hunks + annotations instead of prose
- **`md-slides`** — renders N discrete slides instead of one continuous document
- **`marketing/landing/`** — generates landing pages from scratch (no markdown input)

## Output Artifact

Single `.html` file with 12 derived CSS custom properties, Google Fonts, Prism.js (optional), and all behavior inline.