Skip to content

alirezarezvani/claude-skills / markdown-html/skills/markdown-html-orchestrator

markdown-html-orchestrator

Verified

Use when the user wants a markdown file turned into a single-file interactive HTML page (document, code review or slide deck). Classifies it with doctype_classifier.py and routes to md-document, md-review or md-slides.

references/information_density_canon.md

View on GitHub
# Information Density Canon

**Why this exists:** Thariq Shihipar's central claim is empirical: markdown collapses past ~100 lines because it lacks the visual machinery to manage density. This document anchors that claim in a longer tradition — from Edward Tufte's *Visual Display* to Maggie Appleton's digital gardens — so the orchestrator can defend the 100-line threshold against pushback ("why not 50?", "why not 200?") with cited evidence rather than vibes.

## Core claim

A reader skimming linear markdown loses orientation after roughly 5-7 screens. HTML restores orientation through:
1. **Hierarchy made visible** — typography scale, color, weight, indent, surface
2. **Lateral navigation** — TOC, scrollspy, anchored sections
3. **Lateral structure** — tables, grids, side-by-side comparisons
4. **Lateral interaction** — collapsibles, search, code-copy, hover state

Markdown collapses each of these into the same channel: indented text. HTML opens each into its own channel.

## Sources

### 1. Thariq Shihipar — "Claude Code HTML output" (Medium, 2026)
The spec for this plugin. Key claims used here:
- Threshold ≈ 100 lines: "I stopped reading markdown files past 100 lines. My threshold was about the same. Yours probably is too."
- Three forces converged: agent outputs got longer, editing relationship changed (LLM edits, not human), information became spatial.
- Five advantages: density, clarity, shareability, two-way interaction, context ingestion.
- Examples gallery: `thariqs.github.io/html-effectiveness/` (20 self-contained HTML files across 9 categories).

### 2. Edward Tufte — *The Visual Display of Quantitative Information* (Graphics Press, 1983/2001)
Foundational text on data-ink ratio and small multiples. Specifically:
- Ch. 1, "Graphical Excellence" — graphics should reveal the data; markdown's linear structure conceals comparison.
- Ch. 4, "Data-Ink and Graphical Redesign" — every visual element should earn its place. HTML's collapsibles and tabs are data-ink positive (they reveal more per pixel than the same content laid out linearly).

### 3. Bret Victor — "Up and Down the Ladder of Abstraction" (2011, worrydream.com)
Argues that interactive controls let a reader move fluidly between concrete examples and abstract rules. The "lightweight interactivity" tier of this plugin (search, collapsibles, hover tooltips) is the documents-equivalent: it lets a reader move between TOC abstraction and section detail without losing place.

### 4. Maggie Appleton — *A Brief History & Ethos of the Digital Garden* (2020, maggieappleton.com)
Establishes the "garden" pattern: persistent, interlinked, editable knowledge artifacts rendered as HTML. Reinforces single-file HTML as the right artifact shape for long-form thinking (vs. blog posts as linear sequences). Many of her gardens use the exact patterns this plugin generates: sticky TOC, collapsibles, callouts.

### 5. Amelia Wattenberger — "Why React isn't great for actually building websites" + interactive essay archive (wattenberger.com)
Demonstrates lightweight interactivity in essays without frameworks — IntersectionObserver, vanilla scroll handling, inline SVG. The exact technical patterns md-document uses.

### 6. Bartosz Ciechanowski — *Internal Combustion Engine* and other essays (ciechanow.ski)
The high-water mark of single-page interactive explainers. Each essay is a single HTML file with inline SVG animation and controls. Validates the single-file-HTML-as-artifact thesis at the upper bound.

### 7. GitHub READMEs-as-landing-pages (2021-present)
Empirically, READMEs that exceed ~200 lines either (a) get split into a `docs/` folder or (b) get an HTML-rendered version (e.g., GitBook, Docusaurus, mdBook). The market has already voted on the 100-200-line threshold.

## Practical takeaway for the orchestrator

When `doctype_classifier.below_min_lines` is true, refuse the conversion and quote Shihipar. The threshold is empirically defended and stylistically consistent with the wider canon of information-design discipline.
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall