md-to-html

技能：md-to-html

内容

用途和背景

• 用途： 将 Markdown 转换为独立 HTML：Mermaid 图表、Chart.js、样式化表格、代码高亮、浮动目录。
• 触发条件（适用场景）：
  • 将 .md 渲染或分享为 HTML
  • 文档包含步骤、对比或需要可视化的数据
  • 需要适合在浏览器中查看的专业输出
  • 触发短语：/md-to-html、md2html、将 md 转成 html、渲染 md、从 md 导出 html、可视化文档
• 不适用场景： 不修改源 .md 文件的内容；不在源 .md 文件旁写入 HTML；不适用于拥有独立设计的多页文档站点（应使用 docs-site-macos）。

心智模型

file .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 + 索引 + 日志	是（无产物时除外）	见“交付”部分

规则和能力

• RULE-01（必须）：HTML 输出到 html/ 目录，不得与源 .md 位于同一目录。
• RULE-02（必须）：输出要求（不要交付有问题的页面）——无论是否使用外部模板，生成的 HTML 都必须包含下方“输出要求”中的每一项。
• 能力：读取 Markdown 文件；写入静态 HTML 文件和维基草稿。渲染库（Mermaid、Chart.js）嵌入页面中。

失败边界

• 未找到源 .md 文件 → 阻塞，询问文件路径。
• 外部模板（~/.gemini/...）不存在 → 仍按此处的用途和输出要求进行渲染（不视为错误）。
• 页面缺少任意一项输出要求 → 失败，交付前修复（“不要交付有问题的页面”）。

操作方式

主要工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	确定性	.md 文件路径	读取源文件（如果存在，也读取外部完整说明）	内容	文件不存在 → 阻塞
W02	判断	内容	选择可视化方式：步骤/对比 → Mermaid，数据 → Chart.js，样式化表格、代码高亮、浮动目录	HTML 草稿	—
W03	确定性	HTML	检查是否满足所有输出要求（见下方列表）	完整的检查清单	有缺项 → 修复，然后重复 W03
W04	执行	HTML	写入 html/<文件名>.html	HTML 文件	—
W05	执行	结果	输出报告草稿（见“交付”部分）	草稿 + 索引 + 日志	无产物 → 跳过

各步骤详情（W01–W05 的权威来源）：

输出

HTML → html/ 目录（例如 html/文件名.html）。不得与源 .md 位于同一目录。

输出要求（不要交付有问题的页面）

无论是否使用外部模板，生成的 HTML 都必须包含：

• <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1">，以及有效的 <title>——缺少 viewport 时，目录/表格会在移动设备上溢出。
• :focus-visible{outline:2px solid <accent>;outline-offset:2px}，使浮动目录链接和所有按钮都能显示键盘焦点环。
• 在 table 上设置 font-variant-numeric:tabular-nums（数字列不应抖动）。
• 使用 @media(prefers-reduced-motion:reduce) 跳过 Mermaid/Chart 入场动画，并将 scroll-behavior 设为 auto；添加 html{scroll-behavior:smooth} 和 scroll-margin-top，使目录锚点跳转平滑，且标题不会被任何粘性页眉遮挡。
• 添加 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）需要人工检查。满足检查清单且已记录报告后，停止。

示例

• 正例： /md-to-html llmwiki/wiki/concepts/solid-what-how.md → html/solid-what-how.html 包含浮动目录、使用 tabular-nums 样式化的 WHAT/HOW 表格、viewport、焦点环和 reduced-motion；草稿 DDMMYY-md-to-html-swh.md + 索引/日志行。
• 边界/失败： 构建版本缺少 <meta name="viewport"> → W03 失败（目录/表格在移动设备上溢出）→ 添加后再写入文件；不要将 HTML 写在 .md 源文件旁边。

交付 — 输出报告

完成所有主要技能任务后，向知识库写入一份提案草稿。

步骤

1. 构建文件名：

• 格式：DDMMYY-<ten>.md
• DDMMYY = 今天的日期（例如，2026 年 6 月 2 日为 020626）
• <ten> = 用 2–4 个 kebab-case 单词概括已完成的工作（例如，landing-page-coteccons、brand-kit-fintech、ingest-auth-spec）

2. 写入 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
<One sentence — what this skill invocation produced or decided>

## Output
<Key artefacts, files created/modified, or decisions made>

## 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)_

3. 更新知识库索引和日志：

• llmwiki/wiki/index.md — 追加一行：| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |
• llmwiki/wiki/log.md — 追加：## YYYY-MM-DD — <skill-name> — <ten>

仅当技能未生成任何工件且未做出任何决策时才跳过（例如，纯展示模式 /caveman-stats）。