/md2html

name: md2html
description: Convert long-form Markdown (plan, spec, system design, RFC, runbook, postmortem, brainstorm, notes) into a single self-contained HTML page with Mermaid diagrams, step timelines, callouts, sidebar TOC. Claude-orange light+dark theme. Multi-language. Portable across Claude Code / Codex / Antigravity / any AI agent.
trigger: /md2html

/md2html

Convert a verbose Markdown document into a single, self-contained HTML file that a tired human can actually scan: diagrams instead of paragraphs, step cards instead of numbered lists, callouts for the parts that matter.

Usage

/md2html <file.md>             # output <file>.html next to source
/md2html <file.md> --out X.html # custom output path
/md2html                       # if no arg, ask user which file

Skill files (resolved relative to this SKILL.md)

• `template.html` — HTML skeleton with embedded CSS (Claude orange light+dark), Mermaid CDN, theme toggle, TOC sidebar, footer. Contains `{{PLACEHOLDER}}` strings and `<!-- COMMENT -->` slots.
• `components.md` — catalog of HTML snippets you must copy verbatim (step cards, callouts, mermaid blocks, pros-cons, comparison cards, collapsibles).
• `examples/` — at least one reference `<doc>.md` → `<doc>.html` pair. Read one to calibrate output quality before starting.

**You MUST read all three before writing output.** Do not invent CSS classes or skip the catalog.

What you must do when invoked

Follow these steps in order. Do not skip.

Step 1 — Resolve inputs

1. Determine the source file from the user's invocation. If none given, ask: *"Tệp `.md` nào cần convert?"* and stop. 2. Read the source `.md` fully. 3. Read `template.html` and `components.md` from the same directory as this SKILL.md. 4. Read one example pair under `examples/` to calibrate.

Step 2 — Analyze the source document

Do this analysis silently in your head (or as one short summary line to the user). Identify:

• **Language of the source** — detect from the actual prose, not the filename. Set `<html lang="...">` to the ISO 639-1 code (`en`, `vi`, `zh`, `ja`, `ko`, `es`, `fr`, `de`, `ru`, `ar`, `th`, …) and translate every UI label to that language.

Common samples (extend to any language using the same scheme):

| Key | EN | VI | ZH (中文) | JA (日本語) | KO (한국어) | ES (Español) | |--- |--- |--- |--- |--- |--- |--- | | TOC title | Contents | Mục lục | 目录 | 目次 | 목차 | Contenido | | Read-time | ~N min read | ~N phút đọc | ~N 分钟阅读 | ~N 分で読了 | ~N분 소요 | ~N min de lectura | | Recommended | ★ Recommended | ★ Đề xuất | ★ 推荐 | ★ 推奨 | ★ 추천 | ★ Recomendado | | Key point | Key point | Ý chính | 要点 | 要点 | 핵심 | Idea clave | | Pros | ✓ Pros | ✓ Ưu điểm | ✓ 优点 | ✓ 長所 | ✓ 장점 | ✓ Ventajas | | Cons | ✕ Cons | ✕ Nhược điểm | ✕ 缺点 | ✕ 短所 | ✕ 단점 | ✕ Desventajas | | Print tooltip | Print / Save PDF | In / Lưu PDF | 打印 / 保存 PDF | 印刷 / PDF 保存 | 인쇄 / PDF 저장 | Imprimir / Guardar | | Theme tooltip | Toggle theme | Đổi theme | 切换主题 | テーマ切替 | 테마 전환 | Cambiar tema | | Source: prefix | Source: | Nguồn: | 来源: | ソース: | 소스: | Fuente: |

For any language not listed, translate using the same conventions. The "Recommended" badge is configured via the `--rec-label` CSS variable set on `<html>` (no per-language CSS needed) — see `{{REC_LABEL}}` below.

**RTL languages** (Arabic, Hebrew, Persian) — current template is LTR-only. If source is RTL, also add `dir="rtl"` to `<html>` and consider it a known visual limitation (sidebar will stay on the left).

• **Title** — from first H1 or filename. Title should be ≤ 80 chars.
• **Subtitle** — first paragraph after H1, or the document's TL;DR sentence. ≤ 200 chars.
• **Doc type** — infer one of: `PLAN`, `SPEC`, `SYSTEM DESIGN`, `RFC`, `RUNBOOK`, `POSTMORTEM`, `BRAINSTORM`, `NOTES`. Pick the closest match based on the document's *purpose*, not its filename. Brainstorm = exploring options with rationale; Plan = ordered steps to a goal; Spec = exact behavior contract; System design = architecture + tradeoffs; RFC = proposal seeking feedback; Runbook = operational procedure; Postmortem = incident review. The uppercase code in the eyebrow stays universal; the topbar `BRAND_LABEL` localizes (Plan / Kế hoạch / 计划 / etc).
• **Reading time** — words ÷ 250, round to nearest minute. Format: `~N min read` (EN) or `~N phút đọc` (VI).
• **Section map** — walk each H2/H3 and tag with the BEST component using §11 cheatsheet in `components.md`:
• numbered action list → Timeline
• architecture/flow prose → Mermaid
• "ưu/nhược", "pros/cons" → Pros-Cons
• "option A vs B" → Comparison cards
• critical conclusion → Key-point highlight
• warnings/decisions → Callouts
• long appendix → Collapsible
• everything else → plain `<h2>` + `<p>`

Step 3 — Build the output HTML

1. **Copy** the full `template.html` content into a string. Do NOT use Read-then-Edit on a file you haven't created; instead, build the output buffer in memory then `Write` once. 2. **Replace placeholders** in the template (all values come from Step 2 analysis, language-matched):

• `{{LANG}}` → ISO 639-1 code: `en` / `vi` / `zh` / `ja` / `ko` / `es` / …
• `{{REC_LABEL}}` → text shown on the "Recommended" comparison-card badge,