md-to-html

用途

md-to-html 用于把 Markdown 文件渲染为独立的 HTML 页面。其目标输出是自包含的 HTML，包含 Mermaid 图表、Chart.js 可视化、带样式的表格、代码高亮以及浮动目录（TOC）。

触发场景包括：把 .md 渲染或分享为 HTML；文档包含步骤、对比或需要可视化的数字；需要浏览器就绪的专业输出。触发短语示例：/md-to-html、md2html、biến md thành html、render md、xuất html từ md、visualize doc。

非目标：不修改源 .md 文件内容；不把 HTML 写在源 .md 文件旁边；不是多页面、带独立设计的文档站点（那属于 docs-site-macos）。

主要能力

读取 Markdown 文件，生成静态 HTML 文件与草稿 wiki。
在页面内嵌渲染库（Mermaid、Chart.js）。
根据内容选择可视化方式：步骤/对比用 Mermaid，数字用 Chart.js，带样式的表格、代码高亮、浮动 TOC。

使用方式

心智模型：.md 文件 →（外部完整模板）→ 独立 HTML（Mermaid · Chart.js · 表格 · 代码高亮 · TOC）+ 强制输出要求 → html/<名称>.html → 输出报告草稿。

输入输出约定：

输入：源 .md 文件（必需，内容需渲染）。
输入：完整指令 ~/.gemini/antigravity/skills/md-to-html/SKILL.md（非必需，为外部详细模板；无论是否有该模板，下述输出要求均适用）。
输出：HTML → html/ 目录（例如 html/文件名.html）（必需，不得与源 .md 同目录，自包含）。
输出：输出报告 llmwiki/wiki/sources/draft/DDMMYY-<ten>.md + index + log（必需，除非 0 产物），见 Delivery 部分。

规则：

RULE-01（必须）：输出 HTML → html/ 目录，不得与源 .md 同目录。
RULE-02（必须）：输出要求（不要交付损坏页面）——无论外部模板如何，生成的 HTML 必须包含下方“输出要求”中的每一项。

主工作流：

W01（确定性）：输入 .md 路径，读取源文件（如有外部完整指令也读取），输出内容；找不到文件则 blocked。
W02（判断）：输入内容，选择可视化方式（步骤/对比 → Mermaid，数字 → Chart.js，带样式表格、代码高亮、浮动 TOC），输出 HTML 构建。
W03（确定性）：输入 HTML，检查是否满足输出要求清单，输出检查结果；缺失则修复并重复 W03。
W04（效果）：输入 HTML，写入 html/<文件名>.html，输出 HTML 文件。
W05（效果）：输入结果，输出报告草稿（Delivery 部分），输出 draft + index + log；0 产物则跳过。

输出要求（不要交付损坏页面），生成的 HTML 必须包含，无论外部模板如何：

<meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> 以及真实的 <title>——没有 viewport 时 TOC/表格在移动端会溢出。
:focus-visible{outline:2px solid <accent>;outline-offset:2px}，使浮动 TOC 链接和任何按钮显示键盘焦点环。
表格上使用 font-variant-numeric:tabular-nums（数字列不得抖动）。
@media(prefers-reduced-motion:reduce) 跳过 Mermaid/Chart 入场动画并设置 scroll-behavior:auto；添加 html{scroll-behavior:smooth} + scroll-margin-top，使 TOC 锚点跳转平滑且标题不被任何粘性头部遮挡。
favicon（内联 data-URI 即可）以及信息性图表上的 alt/<title>。

完整指令：~/.gemini/antigravity/skills/md-to-html/SKILL.md

分支：此版本无子分支。

验证与停止：W03 是确定性清单（可在 HTML 中 grep：charset、viewport、<title>、:focus-visible、tabular-nums、prefers-reduced-motion、favicon）。可视化质量（选择 Mermaid 还是 Chart）需人工审阅。当文件位于 html/ 且通过清单、报告已写入时停止。

适用场景

把 .md 渲染或分享为 HTML。
文档包含步骤、对比或需要可视化的数字。
需要浏览器就绪的专业输出。

限制

不修改源 .md 文件内容。
不把 HTML 写在源 .md 文件旁边。
不是多页面、带独立设计的文档站点。
找不到源 .md 文件时 blocked，需询问路径。
外部模板（~/.gemini/...）不存在时，仍按本 Purpose + 输出要求渲染（不视为错误）。
页面缺少输出要求中任一项时视为 failed，交付前需修复。

示例

正面：/md-to-html llmwiki/wiki/concepts/solid-what-how.md → html/solid-what-how.html 含浮动 TOC、WHAT/HOW 表格 styled tabular-nums、viewport + focus ring + reduced-motion；draft DDMMYY-md-to-html-swh.md + index/log 行。

边界/失败：构建缺少 <meta name="viewport"> → W03 失败（TOC/表格在移动端溢出）→ 添加后才写文件；不把 HTML 写在源 .md 旁边。

Delivery — 输出报告

所有主技能任务完成后，向 wiki 写入 propose 草稿。

步骤：

构建文件名：格式 DDMMYY-<ten>.md；DDMMYY = 今天（例如 020626 表示 2026 年 6 月 2 日）；<ten> = 2–4 个 kebab-case 单词，概括所做工作（例如 landing-page-coteccons、brand-kit-fintech、ingest-auth-spec）。
写入 llmwiki/wiki/sources/draft/DDMMYY-<ten>.md：

type: draft title: "DDMMYY-<ten>" status: proposed tags: [<skill-name>, output-report] timestamp: YYYY-MM-DD

DDMMYY-<ten>

Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD

What

Output

Files

File	Action
`path/to/file`	created / modified

Notes

Invoked via: /<skill-name> skill

Origin

Draft: wiki/sources/draft/DDMMYY-<ten>.md
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)

更新 wiki index 与 log： llmwiki/wiki/index.md — 追加一行：| DDMMYY-<ten> | draft | YYYY-MM-DD | llmwiki/wiki/log.md — 追加：## YYYY-MM-DD — <skill-name> — <ten>

仅当技能产生零产物且零决策时跳过（例如纯展示模式如 /caveman-stats）。