haidang1810/md2html

# md2html [](LICENSE) [](#install) [](#install) [](#multi-language)

## 问题所在 你的 AI 刚生成了 2000 字的系统设计。逻辑优美，权衡细致，对比了三种架构方案——但你不忍心读完第二节，因为那不过是终端滚动缓冲区里一堵等宽的文本墙。上周你让它写的那份头脑风暴文档、今天早上那份迁移计划、你一直拖着没看的事故复盘草稿，情况也好不到哪去。团队里也没人会点开你发的 `plan.md` 链接。 ## 这个技能做什么 你输入 `/md2html anydoc.md`。你的 agent 读取该文件，打开本仓库中的 `template.html` + `components.md`，然后在源文件旁边生成一个精美的 HTML 文件。无需构建步骤，无需服务器，无需 Node，无需 Python。 适用于 AI 交给你的任何长文内容： - **计划** — 多周路线图、迁移步骤、上线策略 - **规格说明** — 功能规格、API 规格、数据模型设计 - **系统设计** — 架构文档、RFC 风格提案 - **运维手册** — 操作流程、事件响应步骤 - **事故复盘** — 事件回顾，含时间线 + 根因分析 + 行动项 - **头脑风暴** — 带理由的选项清单、待整理的创意汇总 - **笔记** — 会议纪要、研究摘要，以及其他任何 Markdown 内容 它不是 Markdown 转 HTML 的工具。**它是一个分析器。** agent 决定哪些部分变成 Mermaid 图表，哪些变成带编号的步骤卡片，哪些变成优缺点对比表格，哪些变成可折叠的"深度阅读"面板。最终效果是精心设计的感觉，而非简单转换。 ## 为什么值得占用你的 `~/.claude/skills` 位置 - **读起来像产品页面，不像规格文档。** 侧边栏目录带滚动监听、每个标题都有锚点链接、每个代码块都有复制到剪贴板按钮、顶部有滚动进度条。这些都是你会内置到真实文档站点的功能。 - **用图表替代大段文字。** 三段式流程自动变成 Mermaid `flowchart` 块。权衡讨论变成并排对比卡片。由 agent 决定——你什么都不用写。 - **单个文件。邮件发送。丢进 Slack。飞机上打开。** 自包含的 HTML，内嵌 CSS 和主题 JS。唯一的网络请求是 Mermaid CDN，如果你在意的话也可以内联进去。 - **用户零安装。** 没有 `npm install`。没有 Docker。整个技能就是三个 Markdown/HTML 文件。任何有 AI agent 和 `git clone` 的人都能在一分钟内用起来。 - **跨 agent 可移植。** 在 Claude Code、Codex CLI、Antigravity、Cursor、Continue.dev 中工作方式相同——只要 agent 能读文件、写文件就行。没有 agent 专用代码。 - **源语言 → 输出语言，自动适配。** 越南语规格？越南语界面。中文计划？`目录` 而非 `Contents`。标签表内置八种语言；其他语言由 agent 翻译填充。 - **生产级 UX，不是周末赶工。** WCAG AA 对比度、≥ 40 px 触摸目标、`prefers-reduced-motion`、focus-visible 环、带背景和 ESC 关闭的移动端目录抽屉、跳转至内容链接、完整打印样式表。由一位毫不留情的 UI/UX 工程师审核。 ## 安装说明 ### Claude Code ``` git clone https://github.com/haidang1810/md2html ~/.claude/skills/md2html ``` 重新加载会话后运行： ``` /md2html plan.md ``` → 在源文件旁边输出 `plan.html`。 ### 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 ``` (Codex 的 prompts 目录在不同版本间有所调整——如有需要请修改符号链接目标。) ### Antigravity ``` git clone https://github.com/haidang1810/md2html ~/projects/md2html ``` 打开 Antigravity → **Settings → Custom Agents → New**，粘贴 `SKILL.md` 的内容，并赋予 agent 对 `~/projects/md2html/` 的文件读取权限。 ### 其他 AI agent 如果 agent 支持系统提示或自定义指令，并且能读写本地文件，就可以运行此技能。将仓库克隆到一个稳定路径，把 `SKILL.md` 粘贴到 agent 的自定义指令中，完成。 ## 使用方法 ``` /md2html plan.md # writes plan.html /md2html plan.md --out docs/x.html # custom output path /md2html # prompts for a file ``` agent 根据文档实际内容选择组件： | Markdown 中的内容 | 你得到的效果 | | --- | --- | | 编号动作列表 | 带时间线的步骤卡片 | | "A 调用 B，B 写入数据库" 类描述 | Mermaid `flowchart` | | "优点 / 缺点"、"X 的权衡" | 双栏优缺点对比框 | | "方案 A vs B vs C" | 对比卡片（含 ★ 推荐标记） | | "不要做 X" / "必须做 Y" | 危险/决策提示框 | | 长附录或代码堆 | 可折叠深度阅读面板 | | 关键结论 | 带强调边框的高亮框 | ## 多语言 UI 标签跟随源语言。标签表开箱支持**英语、越南语、中文（中文）、日语（日语）、韩语（韩语）、西班牙语、法语、德语**。其他语言由 agent 对等翻译并设置 `` 及 `--rec-label` CSS 变量。RTL 语言目前仅支持 LTR。 ## 示例 参见 [`examples/example-plan.md`](examples/example-plan.md)（越南语源文件）→ [`examples/example-plan.html`](examples/example-plan.html)（渲染效果）。本 README 顶部的截图来自一份更长的测试规格——一份游戏经济系统设计文档。 ## 自定义主题 所有视觉变量都在 `template.html` 顶部的 CSS 变量中。通过编辑 `:root` 和 `[data-theme="dark"]` 块来更改强调色、表面色、字体、圆角。不要重命名类名——`components.md` 引用了它们。 ``` :root { --accent: #D97757; /* Claude orange — change me */ --bg: #FAFAF7; /* … */ } ``` ## 更新 ``` cd ~/.claude/skills/md2html && git pull ``` ## 卸载 ``` rm -rf ~/.claude/skills/md2html ``` ## 包含内容 ``` md2html/ ├── SKILL.md # Instructions the agent loads on /md2html ├── template.html # HTML skeleton: CSS + Mermaid + theme JS ├── components.md # Component catalog the agent assembles from ├── examples/ # Reference .md → .html pair (gold standard) ├── docs/ # Screenshots for this README ├── LICENSE └── README.md ``` ## 路线图 - [ ] 内联 Mermaid 包（真正的离线模式） - [ ] 更多主题（森林绿、午夜蓝、纸张风格） - [ ] 甘特图/路线图组件 - [ ] 自动检测源文件中的图片并内联 - [ ] RTL 语言支持（阿拉伯语、希伯来语） 欢迎提交 PR——尤其是更多语言的翻译表和主题变体。 ## 许可证 [MIT](LICENSE) © 2026 [haidang1810](https://github.com/haidang1810)

标签：AI辅助文档, Antigravity技能, Callout提示框, Claude AI, Claude Code技能, Codex技能, GPT Agent, I18n, Markdown解析, Markdown转HTML, Mermaid图表, RFC文档, SEO优化, 事故复盘, 二进制发布, 产品规格, 亮色主题, 代码文档, 会议笔记, 分析型转换, 前端展示, 功能词, 单文件输出, 后端开发, 多主题, 多模态安全, 多语言国际化, 多语言支持, 威胁情报, 安全测试框架, 开发者工具, 开源工具, 技术栈, 技术规范, 数据可视化, 文档可视化, 文档工程, 文档生成, 文档美化, 无服务器, 时间线, 暗色主题, 模板引擎, 目录生成, 系统架构文档, 自动化文档, 跨平台, 运行手册, 防御加固, 零依赖, 静态HTML