md-document

---
name: md-document
description: Use when converting long-form markdown specs, reports, or explainers into single-file HTML with TOC, search, and code-copy buttons.
category: Formatting
version: 1.0.0
tools: []
---

# md-document — 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:
- 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.

## 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

## Output Artifact

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

## Asking the Right Questions

1. **What's the intended use?** Skim, decide, or deep-read? Density follows.
2. **Sticky-sidebar TOC or collapsible?** Recommended: sticky for > 800 words / 4+ H2s.
3. **Which interactive features?** Recommended: all four (TOC, search, scrollspy, copy-code).
4. **Does the document have a clear H1 title?** Recommended: yes.