tomevault-io /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>.htmlpair. 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
- Determine the source file from the user's invocation. If none given, ask: "Tệp
.mdnào cần convert?" and stop. - Read the source
.mdfully. - Read
template.htmlandcomponents.mdfrom the same directory as this SKILL.md. - 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-labelCSS 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 topbarBRAND_LABELlocalizes (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
- Copy the full
template.htmlcontent into a string. Do NOT use Read-then-Edit on a file you haven't created; instead, build the output buffer in memory thenWriteonce. - 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-labelCSS 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 "{{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 asaria-labelfor 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)
- Replace
<!-- TOC_ENTRIES -->with one<a>per H2/H3 (see §2 in components.md). Generate stable kebab-caseidfrom heading text. - Replace the slot between
<!-- CONTENT_START -->and<!-- CONTENT_END -->with the document body, section by section, using components fromcomponents.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.
- Start with
- Write the assembled HTML to the output path.
Step 4 — Verify
After writing, do ONE quick sanity check by re-reading just the section you generated (not the whole file):
- Every
id="..."referenced in the TOC exists on a heading. - No leftover
{{PLACEHOLDER}}strings. - Mermaid blocks have valid syntax (use
flowchart,sequenceDiagram,erDiagram,stateDiagram-v2, organtt— never baregraphwithout direction). - No
<script>tags added beyond whattemplate.htmlalready includes.
Report back to the user with:
- Output file path
- 1-line summary of what changed (e.g. "Rendered 7 sections: 1 mermaid flow, 2 step timelines, 4 callouts. ~6 phút đọc.")
- A reminder they can open it with
xdg-open <file>.html(Linux) /open <file>.html(mac).
Critical rules
- Never paraphrase technical content into vague prose. A step
chạy migration 0042_user_schema.sqlmust remain that exact filename — don't change tochạy migration mới. - One component per chunk. Don't wrap a callout inside a step card inside a collapsible. Keep nesting flat.
- Mermaid > prose for any flow ≥ 3 hops. If the source says "A gọi B, B gọi C, C ghi DB", make a diagram.
- Key-point highlights are rare. Max 1 per H2 section, ideally 2-3 total per document.
- UI text follows the detected source language — including for non-EN/non-VI sources (Chinese, Japanese, Korean, Spanish, etc). Use the language sample table in Step 2 or translate equivalently. Code, commands, file names, library names, error messages stay verbatim regardless of language.
- Self-contained output. No external file references except the CDN scripts already in
template.html. - Do not modify
template.htmlorcomponents.md— those are the skill's source of truth. Only Write the output.html. - Use SVG icons only — never emojis. Every icon is
<svg class="..."><use href="#i-NAME"/></svg>referencing the sprite at the top of<body>. See §13 incomponents.mdfor the catalog. No emoji glyphs anywhere in callouts, doc-meta, topbar, or body content. - Anchor links and copy-to-clipboard auto-inject via JS — do NOT add them manually. Just give H2/H3 a proper
id, and put code in<pre><code>. The template's boot script handles the rest. - Wrap wide tables in
.table-wrap— see components.md §14b. Tables ≥ 4 columns or with long cells need the wrapper for mobile scroll. - Use
<figure>+<figcaption>for images with descriptivealt. See components.md §14a.
Cross-AI compatibility
This skill is designed to run identically on:
- Claude Code — install at
~/.claude/skills/md2html/(this directory, symlinked or copied). Invoke with/md2html <file>. - Codex CLI — copy
SKILL.mdcontent to~/.codex/prompts/md2html.md, keeptemplate.htmlandcomponents.mdat a stable absolute path, update the file references in SKILL.md if needed. Invoke with/md2html. - Antigravity — add SKILL.md as a custom prompt/agent instruction, ensure the agent has Read/Write tool access to the skill folder.
The only external dependency is mermaid via CDN (resolved at HTML open time, not at skill execution time). No npm/pip install required for the skill itself.
Edge cases
- Source has no headings — wrap content in one
<h2 id="content">Nội dung</h2>and infer logical breaks from blank lines + topic shifts. - Source has existing mermaid code blocks — keep them, just rewrap in
<figure class="diagram">with caption. - Source has HTML embedded — pass through as-is inside
<div>if safe, else escape. - Source is very short (< 200 words) — skip TOC sidebar (delete
<aside class="toc">block), render as single column. - Source is very long (> 5000 words) — collapse low-priority sections by default with
<details>. - Output file already exists — overwrite. The source
.mdis canonical; HTML is regenerated artifact.
Anti-patterns
- ❌ Generating the HTML in many small Edit calls — produces drift. Build full string, Write once.
- ❌ Adding new CSS via
<style>— extendtemplate.htmlinstead and tell the user. - ❌ Translating proper nouns or code identifiers.
- ❌ "Improving" the source by adding info not in the original.
- ❌ Reporting success without running Step 4 verification.
Source: haidang1810/md2html — distributed by TomeVault.