# Article To HTML

> Render a markdown draft / any document in the conversation context into a single-file "paper proposal" HTML — serif body, monospace meta, numbered sections, inline SVG figures, callouts, tables, optional interactive elements. Trigger when the user says "turn this into HTML / render as a web page / make a pretty HTML / give me a single-page doc / generate article HTML / paper-style HTML / convert to article html / render this as a doc html" or similar, and wants a **static single file** rather than Figma/PDF/PPT. Also fires when the user pastes some markdown and says "beautify this / typeset this / give me a web version". Do NOT trigger when the user wants slides, needs a backend, or needs a multi-page site.

- Skill: `agentara/article-to-html` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add agentara/article-to-html`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agentara/article-to-html/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: agentara (https://skillmd.com/u/agentara)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/agentara/article-to-html

---


# article-to-html

Turn a document (from conversation context or a given markdown file) into a **self-contained HTML file**, reusing the "paper proposal" design system defined in `references/template.html`: serif body + monospace meta + numbered sections + inline SVG figures + callouts + tables + optional JS interactivity.

## Flow after trigger

1. **Get the source.** If the user gave a file path, `Read` it. If the draft is in conversation context, use that directly.
2. **Extract document skeleton.** Title, subtitle, TL;DR, section list, whether figures are needed, whether tables are needed, whether interactivity is needed.
3. **Read the template.** `Read` `references/template.html` and use its full CSS + structure as the scaffold.
4. **Read the component reference.** `Read` `references/components.md` and pick out the snippets you need this round.
5. **If figures are needed:** consult `references/svg-figures.md` and draw with inline SVG (no external image references — keep the file portable).
6. **If interactivity is needed:** consult `references/interactive.md` and append a `<script>` block before `</body>`.
7. **Output.** `Write` to `{same dir as source or current working dir}/{slug}.html`. Filename = English slug of the title, or whatever the user specified.
8. **Report.** One sentence with the file path + a one-line command to open it in a browser.

## Design invariants (do NOT break)

- **Single file.** All CSS / SVG / JS inline. No external fonts, no CDNs, no remote images.
- **Don't change the `paper` palette.** `--paper: #f7f7f5` + `--ink: #1a1a1a` is this skill's visual signature. If the user explicitly asks for a different mood (dark mode, different accent), you can change `--accent` / `--warn`, but keep paper/ink.
- **Serif body + monospace meta.** `body` uses `ui-serif`; every "metadata slot" (`.doc-eyebrow / .doc-meta / th / code / figcaption / .num`) uses `ui-monospace`. This mix is the signature.
- **Section numbering prefix.** `<h2><span class="num">01</span>Section title</h2>` — small monospace, faint gray, 14px gap to the title. Add it even if the source has no numbers.
- **Figures need figcaption.** `<figcaption><span class="fig-num">FIG 1</span>caption text</figcaption>`, the `FIG N` in accent color.
- **TL;DR always on top.** If the source has no TL;DR, condense the first one or two paragraphs into a ~60-word summary and put it there.
- **No "generated by AI" footer watermark** unless the user explicitly asks.

## Component cheat sheet

| If the source contains... | Use... |
|---|---|
| Intro / abstract | `.tldr` block |
| Quotation | `.callout.cite` (with `.cite-source`) |
| Warning / heads-up | `.callout.warn` |
| Generic sidenote | `.callout` (default, white background) |
| Three parallel concepts / roles | `.cards` (three-column cards) |
| N parallel concepts | `.cards cols-2` / `cols-4` |
| Comparison / vendor matrix | `<table>` |
| Flow / architecture / timing / bar chart | inline SVG figure — see `references/svg-figures.md` |
| Open-questions list | `<ol>` with bold lead phrase per item |
| Reference links | `<footer>` containing a `<ul>` |

## Interactive elements (optional)

The template is static by default. Add interactivity **proactively** when the document clearly benefits:

- Section collapse / expand (long documents)
- "Copy" button on code blocks
- Table filter / sort (great for vendor comparison tables)
- Dark mode toggle (persisted to localStorage)
- TOC + scrollspy
- Forms (e.g. for an RFC / decision doc, a "vote / leave comment" form persisted to localStorage)

Specific snippets in `references/interactive.md`. **Default to none** unless (a) the doc is long — ≥3 sections + ≥2 figures, or (b) the source is interaction-shaped (tutorial, decision doc, vendor selection).

## Naming and output location

- Filename: English slug of the title, lowercase, hyphenated, ≤40 chars. For Chinese titles, use pinyin or a translated keyword hint, e.g. 《新基建提案》→ `infra-proposal.html`.
- Output location:
  - If the user gave a source markdown path, output in the **same directory**.
  - Otherwise output in the **current working directory**.
  - If the user specifies a path, honor it.
- If a file with the same name exists, append `-v2` / `-v3`. **Never silently overwrite** the user's existing output.

## Common mistakes

- **Recoloring the CSS.** Don't touch paper/ink/accent unless the user said "different palette please". Visual consistency is the entire point.
- **Switching body to sans-serif.** The whole "proposal paper" feel hinges on the serif body. Changing fonts breaks the look.
- **Using emoji as icons.** The character vocabulary of this skill is uppercase monospace labels + small color blocks (`.mascot` / `.layer-icon`). No emoji unless the user explicitly asks.
- **External `<img src="https://...">`.** Kills portability. Either inline SVG, base64, or omit.
- **Missing figcaption numbers.** The `FIG 1 / FIG 2 / FIG 3` running labels are key to the "academic paper" feel.
- **Callout on every paragraph.** Callouts highlight one or two passages, not decorate. Keep total callouts ≤ 5 per document.
- **Cramming 5 items into the three-column cards.** Switch to `repeat(N, 1fr)` (or use the `.cols-N` modifier), don't force wrap.
- **Leaking domain-specific names from the example.** The template is blank; if the source doesn't mention Crewlet / Anthropic / etc., the HTML shouldn't either.

## File manifest

- `references/template.html` — blank scaffold (full CSS + placeholder structure). Start here.
- `references/components.md` — cut-and-paste HTML snippets for every component.
- `references/svg-figures.md` — five typical SVG figure skeletons (architecture, timing, bar comparison, stacked layers, lifecycle).
- `references/interactive.md` — JS snippets (collapse, copy, table filter/sort, TOC, dark mode, form → localStorage, reading progress, figure zoom).
- `assets/example.html` — a completed reference render (the original Chinese article.html kept as a visual benchmark).