md2html

/md2html

将冗长的 Markdown 文档转换为一个独立的 HTML 文件，让疲惫的读者也能轻松浏览：用图表代替段落，用步骤卡片代替编号列表，并为重要内容添加醒目标注。

用法

/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.md 解析路径）

• template.html — 内嵌 CSS 的 HTML 骨架（Claude 橙色浅色和深色主题）、Mermaid CDN、主题切换、目录侧边栏、页脚。包含 {{PLACEHOLDER}} 字符串和 `` 插槽。
• components.md — HTML 片段目录，必须逐字复制（步骤卡片、醒目标注、mermaid 块、优缺点、对比卡片、可折叠内容）。
• examples/ — 至少包含一组参考 <doc>.md → <doc>.html 文件对。开始前阅读一组，以校准输出质量。

编写输出前，必须阅读以上全部三项。 不要自行编造 CSS 类，也不要跳过目录。

调用时必须执行的操作

按顺序执行以下步骤。不得跳过。

步骤 1 — 确定输入

1. 根据用户的调用确定源文件。如果未提供，请询问：“需要转换哪个 .md 文件？” 然后停止。
2. 完整读取源 .md 文件。
3. 从与此 SKILL.md 相同的目录读取 template.html 和 components.md。
4. 阅读 examples/ 下的一组示例文件，以校准输出。

步骤 2 — 分析源文档

在心中默默完成此分析（或用一行简短摘要告知用户）。确定：

• 源语言 — 根据实际正文判断，而不是文件名。将 <html lang="..."> 设置为 ISO 639-1 代码（en、vi、zh、ja、ko、es、fr、de、ru、ar、th 等），并将每个 UI 标签翻译成该语言。

  常见示例（可按相同规则扩展到任何语言）：

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

  对于未列出的语言，请遵循相同惯例进行翻译。“推荐”徽章通过 <html> 上设置的 --rec-label CSS 变量配置（无需针对每种语言编写 CSS）——详见下方的 {{REC_LABEL}}。

  RTL 语言（阿拉伯语、希伯来语、波斯语）——当前模板仅支持 LTR。如果源文档使用 RTL 语言，也要为 <html> 添加 dir="rtl"，并将其视为已知的视觉限制（侧边栏仍会位于左侧）。

• 标题 — 取自第一个 H1 或文件名。标题应不超过 80 个字符。

• 副标题 — 取自 H1 后的第一段，或文档的 TL;DR 句子。不超过 200 个字符。

• 文档类型 — 从以下类型中推断：PLAN、SPEC、SYSTEM DESIGN、RFC、RUNBOOK、POSTMORTEM、BRAINSTORM、NOTES。根据文档的用途选择最匹配的类型，而非依据文件名。Brainstorm = 探索选项并说明理由；Plan = 为达成目标而按顺序排列的步骤；Spec = 精确的行为约定；System design = 架构与权衡；RFC = 征求反馈的提案；Runbook = 操作流程；Postmortem = 事件复盘。眉题中的大写代码保持通用，顶部栏的 BRAND_LABEL 则应本地化（Plan / Kế hoạch / 计划等）。

• 阅读时间 — 字数 ÷ 250，四舍五入到最接近的分钟。格式：~N min read（EN）或 ~N phút đọc（VI）。

• 章节映射 — 遍历每个 H2/H3，并根据 components.md 中 §11 的速查表标记最合适的组件：

  • 编号步骤列表 → 时间线
  • 架构／流程说明 → Mermaid
  • “优点／缺点”或“pros/cons” → 优缺点
  • “选项 A 与选项 B” → 对比卡片
  • 关键结论 → 要点高亮
  • 警告／决策 → 提示框
  • 较长的附录 → 可折叠区块
  • 其他所有内容 → 普通 <h2> + <p>

步骤 3 — 构建输出 HTML

1. 复制完整的 template.html 内容到字符串中。不要对尚未创建的文件执行“先 Read 再 Edit”；而应先在内存中构建输出缓冲区，然后只执行一次 Write。
2. 替换模板中的占位符（所有值均来自步骤 2 的分析，并与语言匹配）：
   • {{LANG}} → ISO 639-1 代码：en / vi / zh / ja / ko / es / …
   • {{REC_LABEL}} → 显示在对比卡片“推荐”徽标上的文本，例如 ★ Recommended / ★ Đề xuất / ★ 推荐 / ★ 추천。此值会设置 <html> 上的 --rec-label CSS 变量。如果忘记设置，CSS 会回退为 ★ Recommended。
   • {{TITLE}}（出现两次：<title> 和 .doc-title）
   • {{SUBTITLE}}
   • {{DOC_TYPE}} → 通用大写代码：PLAN、SPEC、SYSTEM DESIGN、RFC、RUNBOOK、POSTMORTEM、BRAINSTORM、NOTES
   • {{SOURCE_FILE}} → 源文件的基本名称（例如 plan.md）
   • {{DATE}} → ISO 日期或本地化的“Updated ”
   • {{READ_TIME}} → 本地化的阅读时间，例如 ~3 min read / ~3 phút đọc / ~3 分钟阅读
   • {{BRAND_LABEL}} → 本地化的文档类型标签，用于顶栏
   • {{TOC_TITLE}} → 本地化的“Contents”（也用作 TOC 抽屉的 aria-label）
   • {{PRINT_TOOLTIP}} → 本地化的打印提示
   • {{THEME_TOOLTIP}} → 本地化的主题切换提示
   • {{CLOSE_LABEL}} → 本地化的“Close”（用于移动端 TOC 抽屉的关闭按钮），例如 Close / Đóng / 关闭 / 閉じる
   • {{SKIP_LINK_LABEL}} → 本地化的跳转到正文链接文本，例如 Skip to content / Bỏ qua menu / 跳到正文
   • {{FOOTER_NOTE}} → 本地化的来源署名（例如 Source: plan.md / Nguồn: plan.md / 来源: plan.md）
3. 将 `` 替换为每个 H2/H3 对应的一个 <a>（参见 components.md 中的 §2）。根据标题文本生成稳定的 kebab-case id。
4. 将 和 之间的占位内容替换为文档正文，按章节使用 components.md 中的组件。每个章节必须：
   • 以 <h2 id="..."> 开头（与 TOC 条目一致）。
   • 每个逻辑块使用一个主要组件（不要连续堆叠 3 个提示框）。
   • 保留原意——不要省略技术细节来概括内容；仅精简填充内容或重复部分。
5. 将组装好的 HTML 写入输出路径。

步骤 4 — 验证

写入后，快速重新读取你生成的部分，进行一次简单检查（不要读取整个文件）：

• TOC 中引用的每个 id="..." 都存在于某个标题上。
• 没有遗留的 {{PLACEHOLDER}} 字符串。
• Mermaid 块语法有效（使用 flowchart、sequenceDiagram、erDiagram、stateDiagram-v2 或 gantt；不要使用未指定方向的裸 graph）。
• 除 template.html 中已有的内容外，没有添加 <script> 标签。

向用户报告：

• 输出文件路径
• 一行变更摘要（例如："已渲染 7 个章节：1 个 Mermaid 流程图、2 个步骤时间线、4 个提示框。阅读时间约 6 分钟。"
• 提醒用户可以使用 xdg-open <file>.html（Linux）或 open <file>.html（mac）打开文件。

关键规则

1. 绝不要把技术内容改写成含糊的文字。 步骤 chạy migration 0042_user_schema.sql 必须原样保留文件名——不要改成 chạy migration mới。
2. 每个块只包含一个组件。 不要在步骤卡片中嵌套提示框，也不要在可折叠内容中嵌套步骤卡片。保持扁平嵌套。
3. 凡是包含 ≥ 3 个环节的流程，都优先使用 Mermaid，而不是文字描述。 如果原文说“A 调用 B，B 调用 C，C 写入 DB”，就制作一张图。
4. 关键点高亮应少用。 每个 H2 章节最多 1 处，整篇文档最好总共 2-3 处。
5. UI 文本应使用检测到的源语言——包括非英语和非越南语源文本（中文、日语、韩语、西班牙语等）。使用步骤 2 中的语言示例表，或进行等效翻译。代码、命令、文件名、库名和错误消息无论源语言为何，都必须保持原样。
6. 输出必须自包含。 除 template.html 中已有的 CDN 脚本外，不得引用外部文件。
7. 不要修改 template.html 或 components.md——它们是此技能的权威来源。只写入输出 .html。
8. 只使用 SVG 图标——绝不要使用表情符号。 每个图标都必须是 <svg class="..."><use href="#i-NAME"/></svg>，并引用 <body> 顶部的精灵图。图标目录见 components.md §13。提示框、doc-meta、topbar 或正文内容中不得出现任何表情符号字符。
9. 锚点链接和复制到剪贴板功能会由 JS 自动注入——不要手动添加。只需为 H2/H3 设置恰当的 id，并将代码放在 <pre><code> 中。模板的启动脚本会处理其余部分。
10. 宽表格要放在 .table-wrap 中——参见 components.md §14b。列数 ≥ 4 或单元格内容较长的表格需要使用此包装元素，以便在移动设备上滚动。
11. 图片要使用 <figure> + <figcaption>，并提供描述性 alt。参见 components.md §14a。

跨 AI 兼容性

此技能旨在以下环境中以相同方式运行：

• Claude Code — 安装到 ~/.claude/skills/md2html/（此目录，可使用符号链接或复制）。使用 /md2html <file> 调用。
• Codex CLI — 将 SKILL.md 内容复制到 ~/.codex/prompts/md2html.md，将 template.html 和 components.md 保存在稳定的绝对路径下，并在需要时更新 SKILL.md 中的文件引用。使用 /md2html 调用。
• Antigravity — 将 SKILL.md 添加为自定义提示词/Agent 指令，并确保 Agent 对技能文件夹具有 Read/Write 工具权限。

唯一的外部依赖是通过 CDN 加载的 mermaid（在打开 HTML 时解析，而非在执行技能时解析）。技能本身无需安装 npm/pip。

边缘情况

• 源文件没有标题 — 将内容放在一个 <h2 id="content">Nội dung</h2> 下，并根据空行和主题变化推断逻辑分段。
• 源文件包含现有的 mermaid 代码块 — 保留它们，只需用 <figure class="diagram"> 包裹并添加标题。
• 源文件中嵌入了 HTML — 如果安全，则在 <div> 中原样保留；否则进行转义。
• 源文件很短（< 200 words） — 跳过 TOC 侧边栏（删除 <aside class="toc"> 块），按单栏布局呈现。
• 源文件很长（> 5000 words） — 默认使用 <details> 折叠低优先级章节。
• 输出文件已存在 — 覆盖。源 .md 文件为准；HTML 是重新生成的产物。

反面模式

• ❌ 通过多次小型 Edit 调用生成 HTML——这会导致内容偏移。先构建完整字符串，再一次性 Write。
• ❌ 通过 <style> 添加新 CSS——应扩展 template.html，并告知用户。
• ❌ 翻译专有名词或代码标识符。
• ❌ 通过添加原文中没有的信息来“改进”源文件。
• ❌ 未运行步骤 4 验证就报告成功。