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, e.g. ★ Recommended / ★ Đề xuất / ★ 推荐 / ★ 추천. Sets the --rec-label CSS variable on <html>. If you forget this, CSS falls back to ★ Recommended.
   • {{TITLE}} (appears twice: <title> and .doc-title)
   • {{SUBTITLE}}
   • {{DOC_TYPE}} → universal uppercase code: PLAN, SPEC, SYSTEM DESIGN, RFC, RUNBOOK, POSTMORTEM, BRAINSTORM, NOTES
   • {{SOURCE_FILE}} → basename of source (e.g. plan.md)
   • {{DATE}} → ISO date or localized "Updated <today>"
   • {{READ_TIME}} → localized reading time, e.g. ~3 min read / ~3 phút đọc / ~3 分钟阅读
   • {{BRAND_LABEL}} → localized doc-type label for the topbar
   • {{TOC_TITLE}} → localized "Contents" (also used as aria-label for the TOC drawer)
   • {{PRINT_TOOLTIP}} → localized print tooltip
   • {{THEME_TOOLTIP}} → localized theme-toggle tooltip
   • {{CLOSE_LABEL}} → localized "Close" (used for the mobile TOC drawer close button), e.g. Close / Đóng / 关闭 / 閉じる
   • {{SKIP_LINK_LABEL}} → localized skip-to-content link text, e.g. Skip to content / Bỏ qua menu / 跳到正文
   • {{FOOTER_NOTE}} → localized source attribution (e.g. Source: plan.md / Nguồn: plan.md / 来源: plan.md)
3. Replace <!-- TOC_ENTRIES --> with one <a> per H2/H3 (see §2 in components.md). Generate stable kebab-case id from heading text.
4. Replace the slot between <!-- CONTENT_START --> and <!-- CONTENT_END --> with the document body, section by section, using components from components.md. Each section must:
   • Start with <h2 id="..."> (matching the TOC entry).
   • Use ONE primary component per logical chunk (don't stack 3 callouts in a row).
   • Preserve original meaning — do not summarize away technical detail; condense only filler/repetition.
5. Write the assembled HTML to the output path.