md-document — Long-form Markdown to HTML
The general-purpose converter — handles the 90% case Shihipar describes (specs, plans, RFCs, reports, explainers). Three stdlib tools pipeline together:
markdown_parser.py → html_renderer.py → interactivity_injector.py
(md → JSON AST) (AST + tokens → HTML) (HTML + JS behavior)
Output is one .html file with sticky TOC, search filter, scrollspy, code-copy buttons, and the user's 12 derived brand tokens. Externals limited to Google Fonts CSS + Prism.js CDN.
When to invoke
| Symptom |
Action |
markdown-html-orchestrator routes input as DOCUMENT |
Invoke this skill |
User runs /cs:md-document <path>.md directly |
Invoke this skill |
| User says "convert this spec/report/RFC/plan to HTML" |
Invoke this skill |
Input is a code review (has ```diff blocks) |
Route to md-review instead |
Input is a slide deck (clear --- boundaries) |
Route to md-slides instead |
| Input is < 100 lines |
Refuse (Shihipar threshold — markdown still wins) |
| Design-system not onboarded |
Refuse, surface /cs:design-system |
Pipeline
# 1. Parse markdown → JSON AST
python3 markdown-html/skills/md-document/scripts/markdown_parser.py \
--input <path>.md --output sections.json
# 2. Render AST + design-system config → single-file HTML
python3 markdown-html/skills/md-document/scripts/html_renderer.py \
--sections sections.json --output document.html
# 3. Inject lightweight JS (search, copycode, smoothscroll, scrollspy)
python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
--file document.html \
--features search,copycode,smoothscroll,scrollspy
Or all-in-one (sample render):
python3 markdown-html/skills/md-document/scripts/html_renderer.py --sample \
| python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
--file /dev/stdin --output document.html
What gets rendered
CommonMark subset sufficient for agent-generated artifacts:
- Headings H1-H6 (every H2+ gets an anchor id and TOC entry)
- Paragraphs with inline bold / italic /
code / links /
- 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 (rendered as plain text), reference-style links.
Hard rules
- Refuses input < 100 lines. Markdown wins below the threshold (Shihipar).
- Refuses without onboarding.
config_loader.setup_completed() must return True. Otherwise surface /cs:design-system.
- Single-file output. All CSS + JS inline. Only externals are
fonts.googleapis.com and cdn.jsdelivr.net (Prism). Anything else is a regression.
- Customization must change behavior.
design_style=editorial produces 720px-wide layout with 1.75 line-height; playful rounds the callouts and adds shadow; technical is dense with 0.875rem code. Smoke-tested.
- WCAG-compliant tokens. Inherits the design-system's WCAG AA palette — body text ≥ 4.5:1 contrast, links iteratively walked to 4.5:1.
- Idempotent injection. Re-injecting interactivity is a no-op (marker check). Re-rendering with a different design_style works cleanly.
Forcing-question library (Matt Pocock grill discipline)
- What's the document for — skim, decide, or deep-read? Recommended: name it; density follows. Canon: Shihipar; Tufte Envisioning Information.
- Sticky-sidebar TOC or collapsible-top? Recommended: sticky-sidebar for > 800 words / 4+ H2s; collapsible-top for shorter mobile-first docs. Canon: NN/g TOC Best Practices (2023).
- All four interactive features, or a subset? Recommended: all four — none of them cost more than ~1 KB. Canon: Wattenberger Why React isn't great for actually building websites.
- Code theme — light, dark, or auto? Recommended: auto (follows OS
prefers-color-scheme). Canon: WCAG 2.2 §1.4.3.
- Does the document have a clear H1 title? Recommended: yes — H1 becomes the page
<title> and is excluded from the TOC.
Distinct from
md-review — that converter renders diff blocks + severity-tagged margin annotations. This one renders prose + tables + code + callouts.md-slides — that converter splits on --- boundaries into slides. This one renders one continuous document.marketing/landing/ — that generates landing pages from scratch (no markdown input). This converts existing markdown.
Output artifact
{default_output_dir}/doc-{slug}.html (path resolved by orchestrator's output_path_resolver.py; collision suffix -2, -3, … by default).
References
- Shihipar — Claude Code HTML output (Medium, 2026)
- Tufte — Envisioning Information (1990), ch. 2 "Micro/Macro Readings"
- NN/g — Table of Contents Best Practices (2023)
- WCAG 2.2 — §1.4.3 contrast, §2.4.5 multiple ways
- Wattenberger — Why React isn't great for actually building websites
- See
references/ for full citations
1---2name: md-document3description: Converts long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file, lightly-interactive HTML document with sticky TOC, scrollspy, search filter, code-copy buttons, and design-system-driven brand tokens. Triggers when the markdown-html-orchestrator classifies an input as DOCUMENT, or when invoked directly via /cs:md-document. Reads the design-system config via config_loader.py and inlines the user's 12 derived CSS custom properties; refuses to render if onboarding hasn't run. Single-file output — Google Fonts + Prism.js CDN are the only externals; no framework runtime, no build step. Use after orchestrator routing or after design-system onboarding is confirmed.4license: MIT5---67# md-document — Long-form Markdown to HTML89The general-purpose converter — handles the 90% case Shihipar describes (specs, plans, RFCs, reports, explainers). Three stdlib tools pipeline together:1011```12markdown_parser.py → html_renderer.py → interactivity_injector.py13 (md → JSON AST) (AST + tokens → HTML) (HTML + JS behavior)14```1516Output is one `.html` file with sticky TOC, search filter, scrollspy, code-copy buttons, and the user's 12 derived brand tokens. Externals limited to Google Fonts CSS + Prism.js CDN.1718## When to invoke1920| Symptom | Action |21|---|---|22| `markdown-html-orchestrator` routes input as DOCUMENT | Invoke this skill |23| User runs `/cs:md-document <path>.md` directly | Invoke this skill |24| User says "convert this spec/report/RFC/plan to HTML" | Invoke this skill |25| Input is a code review (has ` ```diff ` blocks) | Route to `md-review` instead |26| Input is a slide deck (clear `---` boundaries) | Route to `md-slides` instead |27| Input is < 100 lines | Refuse (Shihipar threshold — markdown still wins) |28| Design-system not onboarded | Refuse, surface `/cs:design-system` |2930## Pipeline3132```bash33# 1. Parse markdown → JSON AST34python3 markdown-html/skills/md-document/scripts/markdown_parser.py \35 --input <path>.md --output sections.json3637# 2. Render AST + design-system config → single-file HTML38python3 markdown-html/skills/md-document/scripts/html_renderer.py \39 --sections sections.json --output document.html4041# 3. Inject lightweight JS (search, copycode, smoothscroll, scrollspy)42python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \43 --file document.html \44 --features search,copycode,smoothscroll,scrollspy45```4647Or all-in-one (sample render):4849```bash50python3 markdown-html/skills/md-document/scripts/html_renderer.py --sample \51 | python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \52 --file /dev/stdin --output document.html53```5455## What gets rendered5657CommonMark subset sufficient for agent-generated artifacts:58- Headings H1-H6 (every H2+ gets an anchor id and TOC entry)59- Paragraphs with inline **bold** / *italic* / `code` / [links](url) / 60- Fenced code blocks (` ```python `) with Prism.js highlighting on demand61- GFM tables with per-column alignment62- GFM callouts (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`)63- Blockquotes, ordered + unordered lists (single-level), horizontal rules6465Out of scope: nested lists, HTML inlines, footnotes, definition lists, task list checkboxes (rendered as plain text), reference-style links.6667## Hard rules68691. **Refuses input < 100 lines.** Markdown wins below the threshold (Shihipar).702. **Refuses without onboarding.** `config_loader.setup_completed()` must return `True`. Otherwise surface `/cs:design-system`.713. **Single-file output.** All CSS + JS inline. Only externals are `fonts.googleapis.com` and `cdn.jsdelivr.net` (Prism). Anything else is a regression.724. **Customization must change behavior.** `design_style=editorial` produces 720px-wide layout with 1.75 line-height; `playful` rounds the callouts and adds shadow; `technical` is dense with 0.875rem code. Smoke-tested.735. **WCAG-compliant tokens.** Inherits the design-system's WCAG AA palette — body text ≥ 4.5:1 contrast, links iteratively walked to 4.5:1.746. **Idempotent injection.** Re-injecting interactivity is a no-op (marker check). Re-rendering with a different design_style works cleanly.7576## Forcing-question library (Matt Pocock grill discipline)77781. **What's the document for — skim, decide, or deep-read?** Recommended: name it; density follows. Canon: Shihipar; Tufte *Envisioning Information*.792. **Sticky-sidebar TOC or collapsible-top?** Recommended: sticky-sidebar for > 800 words / 4+ H2s; collapsible-top for shorter mobile-first docs. Canon: NN/g *TOC Best Practices* (2023).803. **All four interactive features, or a subset?** Recommended: all four — none of them cost more than ~1 KB. Canon: Wattenberger *Why React isn't great for actually building websites*.814. **Code theme — light, dark, or auto?** Recommended: auto (follows OS `prefers-color-scheme`). Canon: WCAG 2.2 §1.4.3.825. **Does the document have a clear H1 title?** Recommended: yes — H1 becomes the page `<title>` and is excluded from the TOC.8384## Distinct from8586- **`md-review`** — that converter renders diff blocks + severity-tagged margin annotations. This one renders prose + tables + code + callouts.87- **`md-slides`** — that converter splits on `---` boundaries into slides. This one renders one continuous document.88- **`marketing/landing/`** — that generates landing pages from scratch (no markdown input). This converts existing markdown.8990## Output artifact9192`{default_output_dir}/doc-{slug}.html` (path resolved by orchestrator's `output_path_resolver.py`; collision suffix `-2`, `-3`, … by default).9394## References9596- Shihipar — *Claude Code HTML output* (Medium, 2026)97- Tufte — *Envisioning Information* (1990), ch. 2 "Micro/Macro Readings"98- NN/g — *Table of Contents Best Practices* (2023)99- WCAG 2.2 — §1.4.3 contrast, §2.4.5 multiple ways100- Wattenberger — *Why React isn't great for actually building websites*101- See `references/` for full citations
belentani7