md2html 

在 AI 辅助编程与写作日益普及的今天，我们常面临一个尴尬局面：AI 生成了逻辑严密、内容丰富的长篇文档（如系统架构、迁移计划、事后分析），但最终以纯文本 Markdown 形式呈现时，却变成了一堵难以阅读的“等宽文本墙”。md2html 是一个专为 Claude Code、Codex、Antigravity 等 AI 代理设计的可移植技能，它能智能分析 Markdown 内容，将其转换为包含侧边栏目录、Mermaid 图表、步骤时间线及交互组件的单文件独立 HTML 页面。

无需任何构建步骤、服务器或运行时环境（Node/Python），md2html 让每一份 AI 生成的文档都拥有产品级网站的阅读体验，且便于通过邮件、Slack 分享或在离线环境下打开。

核心亮点：智能可视化、单文件便携、零依赖

1. 智能组件映射，拒绝“文本墙”

md2html 不仅仅是一个转换器，更是一个内容分析器。AI 代理会根据语义自动决定最佳展示形式：

• 流程变图表：识别操作步骤或系统交互，自动生成 Mermaid 流程图或序列图。
• 权衡变卡片：将“优点/缺点”或“方案 A vs B”转化为并排的对比卡片，直观呈现决策依据。
• 步骤变时间线：带编号的操作列表自动渲染为带有轨道连接的步骤时间线卡片。
• 重点变标注：识别“警告”、“必须做”等语境，生成醒目的危险/决策标注框。
• 长文变折叠：将附录、代码 dump 或非核心细节放入可折叠的**“深入探讨”面板**，保持主界面整洁。

2. 单文件独立 HTML，极致便携

• 自包含资源：所有 CSS、JavaScript 及主题配置均内嵌于单个 .html 文件中。
• 零网络依赖：除可选的 Mermaid CDN 外，无需加载外部资源，可在飞机上、内网或离线环境中完美打开。
• 易于分享：直接拖入 Slack、通过邮件发送附件，接收方无需安装任何软件即可查看精美排版。

3. 多语言适配与无障碍设计

• 自动语言检测：内置英、中、日、韩、越、西、法、德八种语言的界面标签表。若源文档为中文，目录自动显示为“目录”而非“Contents”。
• 生产级 UX：
  • WCAG AA 标准：确保高对比度与焦点可见环，保障视障用户可读性。
  • 响应式设计：适配移动端触摸目标（≥40px），提供带背景遮罩的侧边栏抽屉。
  • 打印优化：内置完整的打印样式表，方便导出纸质文档。
  • 深色/浅色主题：默认采用优雅的 Claude 橙色主题，支持系统偏好自动切换。

4. 跨代理通用，零安装门槛

• 广泛兼容：适用于 Claude Code、Codex CLI、Antigravity、Cursor、Continue.dev 等任何支持读取本地文件与系统提示的 AI 代理。
• 无环境依赖：无需 npm install，无需 Docker，无需 Python。整个技能仅由三个文件（SKILL.md, template.html, components.md）组成，任何人都能在一分钟内部署使用。

快速开始

1. 安装技能

对于 Claude Code 用户：

git clone https://github.com/haidang1810/md2html ~/.claude/skills/md2html

重新加载会话后生效。

对于 Codex CLI 用户：

git clone https://github.com/haidang1810/md2html ~/.config/md2html
mkdir -p ~/.codex/prompts
ln -s ~/.config/md2html/SKILL.md ~/.codex/prompts/md2html.md

对于 Antigravity 用户：

1. 克隆仓库至本地路径（如 ~/projects/md2html）。
2. 在 Antigravity 设置中创建自定义代理，粘贴 SKILL.md 内容。
3. 授予代理读取该路径的文件权限。

对于其他 AI 代理：
将仓库克隆至稳定路径，并将 SKILL.md 的内容粘贴到代理的系统提示（System Prompt）或自定义指令中，确保代理拥有读写本地文件的权限。

2. 使用命令

在对话中输入以下指令即可：

# 基本用法：将 plan.md 转换为 plan.html
/md2html plan.md

# 指定输出路径
/md2html plan.md --out docs/x.html

# 交互式选择文件
/md2html

3. 效果示例

假设你的 Markdown 包含以下内容：

## 架构对比
- 方案 A：单体应用，开发快但扩展难。
- 方案 B：微服务，扩展好但运维复杂。

## 部署步骤
1. 构建镜像
2. 推送至 Registry
3. 更新 K8s Deployment

md2html 将生成：

• 一个包含两列布局的对比卡片，清晰展示方案 A/B 的优劣。
• 一个带有连接线的垂直时间线，可视化展示三个部署步骤。
• 左侧固定的滚动监听目录，方便快速跳转。