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/single_file_html_discipline.md

View on GitHub
# Single-File HTML Discipline

**Why this exists:** Multi-file HTML output (separate CSS, JS, images, asset folders) breaks the central value proposition: shareability. The recipient can't drop the file into Slack, attach it to an email, or upload it to a static host with one drag. This document codifies the single-file constraint and names the few permitted exceptions.

## The constraint

Every converter (md-document, md-review, md-slides) MUST produce one `.html` file containing all CSS and all JavaScript inline. The only externals permitted are:

1. **Google Fonts CSS** — pulled from `fonts.googleapis.com` via `<link rel="stylesheet">`. Falls back to system stack if blocked.
2. **Prism.js** — pulled from `cdn.jsdelivr.net` or `cdnjs.cloudflare.com` for syntax highlighting. Falls back to plain `<pre>` if blocked.

No other CDN. No build step. No bundler. No framework runtime.

## Why

### Shareability
A single .html file uploads to S3, Vercel, Netlify, or any static host in one operation. It also opens in a recipient's browser without a server, which means it works in:
- Slack DM previews
- Email attachments (Gmail / Outlook web)
- Local `file://` URLs
- GitHub `raw.githubusercontent.com` links
- USB sticks given to a non-technical reviewer

Multi-file output breaks every one of those flows. The marketing/landing/ skill made the same choice for the same reason.

### Portability
Single-file HTML survives copying, archiving, and email-attachment workflows. It's the closest thing to PDF that the web has, with the advantage of being editable and searchable.

### No build-step regret
The moment you require a build step, you require: a Node version, a package.json, a node_modules folder, a transpiler, a watcher, a runtime, and a deployment story. None of that survives "send this to a teammate."

## Permitted CDN externals — discipline

```html
<!-- Google Fonts (CSS only — woff files lazy-loaded by browser) -->
<link rel="preconnect" href="https://fonts.googleapis.com" crossorigin>
<link rel="stylesheet"
      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap">

<!-- Prism.js core + theme + autoloader (gracefully degrades without it) -->
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css">
<script defer
        src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-core.min.js"></script>
<script defer
        src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/plugins/autoloader/prism-autoloader.min.js"></script>
```

Both fall back gracefully: if the CDN is blocked, fonts default to the system stack and code blocks render as plain `<pre>`. The page is still readable, still searchable, still copy-pasteable.

## Anti-patterns

- ❌ External CSS file (`<link rel="stylesheet" href="./style.css">`) — recipient gets a broken page.
- ❌ External JS file (`<script src="./app.js">`) — same problem.
- ❌ External image references for hero/logo (`<img src="./logo.png">`) — base64-embed instead.
- ❌ React/Vue/Svelte/Alpine runtime — vanilla JS only.
- ❌ Tailwind via CDN (`cdn.tailwindcss.com`) — 200 KB of unused CSS; just inline what you use.
- ❌ Web Components requiring a custom-element registry from CDN — same problem.

## Sources

### 1. Thariq Shihipar — "Claude Code HTML output" (Medium, 2026)
"Every playground is a single HTML file with all CSS and JavaScript inlined. No external dependencies. No build step. Open it in any browser." (Playground plugin section — same discipline applies to converted documents.)

### 2. marketing/landing/skills/landing/SKILL.md §"Single-File HTML Discipline"
Established the rule for this repo. Marketing landing pages were the first artifact type to require single-file output; this plugin inherits the discipline directly.

### 3. Tom MacWright — "Big" (github.com/tmcw/big, MIT)
A presentation tool that compiles to a single HTML file. Demonstrates the upper bound of what's possible with the constraint (full slide deck, presenter mode, navigation, in one file).

### 4. Mozilla MDN — *Performance: Reducing HTTP Requests*
Single-file output minimizes round trips. Even on fast networks, a single 200 KB HTML file beats one HTML + three CSS + five JS + four image requests.

### 5. The Web We Lost — Anil Dash (2012, dashes.com)
Argues for portable, host-anywhere web artifacts as a counter to platform lock-in. Single-file HTML is the most portable web artifact possible — no platform, no JS framework, no server.

### 6. Prism.js documentation (prismjs.com)
Lightweight syntax highlighter (~2 KB core + per-language plugins on demand) designed for CDN delivery. The right tradeoff for "single-file with one allowed external."

### 7. Google Fonts API documentation (developers.google.com/fonts/docs/css2)
The `display=swap` parameter ensures system-font fallback while web fonts load, preventing FOUT/FOIT on slow connections. Required parameter for every Google Fonts link the converters emit.

## Applied to markdown-html

`md-document/scripts/html_renderer.py`, `md-review/scripts/review_html_renderer.py`, and `md-slides/scripts/deck_html_renderer.py` all emit single-file output with exactly the two permitted externals. Anything else is a regression.
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