单文件自包含
CSS/JS/图标全部内联，不引任何 CDN、字体、图片。双击离线可打开，这是最核心的诉求，校验脚本会拦下外部引用。
TL;DR
- 单文件自包含：CSS/JS/图标全内联，双击离线打开，可打印转 PDF。
- 一套骨架多套观感：按内容体裁切换风格主题，深浅色自动跟随系统。
- 四种产出：HTML 本体之外，还能出长图、A4 分页图、分享摘要卡。
它解决什么问题
平时积累的内容——对话里一段讲透的答案、一篇技术笔记、一段带代码的教程——想正式化、发给别人、放进仓库时，常常卡在两难：Markdown 打开是一屏灰白，重新排版成网页又要跟外部依赖缠斗半天。html-guide 把「排成一份像样的文档」变成标准化流程：给出内容，它核实事实、判定结构、套用设计体系，交回一个单文件成品。
1单文件自包含
9套风格主题
4种产出形态
0外部依赖 / CDN
💡本页即示例
你现在看的这一页就是 html-guide 的产物：侧边目录、深浅色切换、Ctrl+K 章节跳转、代码复制、打印导出，全部来自它内置的骨架。双击这个 HTML 文件即可离线打开。
三条不可违背的硬规则
skill[1] 把这三条标为「不可违背」——它们是产出质量的兜底。
联网核实
涉及事实、数字、命令、版本先联网核实再写，不凭记忆写死。否定性主张（跑不动 / 不支持 / 门槛高）先穷尽社区反例再断言，来源收进「参考来源」区。
先判断再写
动手前先判定文档类型（教程 / 讲解 / 选型 / 速查 / 代码指南），按类型选结构与组件，而不是套固定模板。
工作流程：六步从内容到成品
每次生成走同一条管线，每步带检查点（GATE）——条件不满足就不进下一步。
-
1
接收与归一化内容
接受对话回答、粘贴的 Markdown、本地文件、网页 URL 或纯主题，统一成可用正文，记下缺失的环节。
产出：内容已归一化，可判定文档类型。 -
2
判定文档类型
按内容信号判为 procedure / explainer / decision / reference（可叠加 code-guide），读结构指南选骨架；再确认输出物与风格主题。
产出：页面骨架（章节顺序）与风格已确定。 -
3
联网核实与补充
对事实、命令、版本、概念逐条核实；「能不能 / 门槛多高」这类可行性主张先穷尽社区衍生路线与真实实测再断言。每核一条记一个来源。
产出：关键信息已核实，来源清单就绪。 -
4
撰写 HTML
以 skeleton.html 为起点，按设计体系的组件类名写正文；正文里的命令、数字带可点击上标引用。
产出：单文件 HTML 已保存。 -
5
自检与交付
跑
check_html.py到 0 error；过结构、证据、防废话三关；可选无头渲染验证骨架 JS 生效。产出：交付可离线打开、可打印的成品。 -
6
按需生成其他输出
长图 / A4 分页 / 摘要卡，按第 2 步的勾选用同一套风格导出。
产出：长图、分页图、分享卡（如勾选）。
文档类型自适应：结构跟着内容走
判定看内容信号，再读 structure-guide.md[3] 对应章节组织骨架。混合内容识别主体类型，叠加次要类型的局部组件。
| 类型 | 内容信号 | 骨架主线 |
|---|---|---|
| procedure 操作教程 | 命令序列、步骤、before/after | 目标与产出 → 准备 → 步骤 → 验证/常见错误 → 扩展 |
| explainer 知识讲解 | 概念、机制、为什么 | 一句话结论 → 背景 → 概念 → 原理 → 要点/误区 |
| decision 决策指南 | 方案对比、选型、权衡 | 背景 → 候选一览 → 逐项深比 → 综合对比 → 结论与推荐 |
| reference 参考手册 | 术语、配置、命令速查 | 快速总览 → 条目列表 → 用法模式（带吸顶搜索） |
| code-guide 代码指南（叠加态） | 大量代码 / 配置文件 | 叠加在上述类型之上，代码带语言标签 + 复制 |
设计体系：一套骨架，多套观感
所有页面共用一套设计令牌与组件库[2]：正文用同一批类名，最后在 <html data-style="…"> 写一个属性换整套观感。深浅色自动跟随系统，打印转 PDF 强制浅色。
读者跳过它会损失信息或定位吗？损失 → 留；只好看 → 删——设计体系 §1.5「反 AI 味」的生动判据
| 风格 | data-style | 视觉签名 | 适合内容 |
|---|---|---|---|
| 现代（默认） | （不写） | 黑体正文 + 宋体大标题 + indigo | 教程 / 速查 |
| 报纸 | newspaper | 墨黑白高对比、衬线密排、红点缀 | 新闻综述、时间线 |
| 杂志 | magazine | 暖纸底、森林绿、衬线大标题 | 观点长文、深度讲解 |
| 极简 | minimal | 薄线、巨留白、近无色 | 数据横评、速查 |
| 学术* | academic* | modern + 衬线正文 + 编号标题 | 论文 / 规范整理 |
| 粗野 | brutal | 粗黑边、硬偏移阴影、高饱和色块 | 海报式、大胆主题 |
| 终端 | terminal | 深底等宽、绿 / 青、$ 提示符 | 命令行 / 开发者教程 |
| 深色科技 | tech | 近黑底、单强调色、细字重 | 产品 / API 说明 |
| 瑞士国际 | swiss | 白底无衬线、瑞士红、发丝线网格 | 结构化说明、数据面 |
| 书卷 | book | 暖纸底、宋体正文、两端对齐、段首缩进 | 长文讲解、经典书排 |
* 学术为 modern 的组合变体（衬线正文 + 编号标题），非独立 data-style。
页面自带的能力，无需手写
骨架内置一批交互，作者写正文时不用碰它们：
自动目录
两级目录由 JS 从正文 h2/h3 生成，滚动高亮当前章节。
代码高亮 + 复制
按语言自动高亮，右上角带语言标签；复制自动剔除 $ 提示符。
Ctrl+K 章节跳转
输入即过滤标题，↑↓ 选择、Enter 跳转、Esc 关闭，键盘优先。
深浅色切换
浅 / 深 / 跟随系统三档，切换带过渡；打印强制浅色。
标题深链 ¶
hover 任意小节标题出现 ¶，点一下直达并可复制链接。
速查表过滤
搜索框吸顶，输入即过滤卡片 / 表格行，适合命令速查类页面。
另有顶部阅读进度条、阅读时长估算、打印 / 导出 PDF（折叠内容自动展开）、回到顶部。
四种产出形态
同一份内容，按分发渠道选形态；HTML 是本体，其余是它的导出。
HTML 本体
单文件、含全部交互，可打印转 PDF。发仓库、发邮件、离线收藏都靠它。
长图
整页滚成一张纵向长图，适合手机看图 / 图文混排；超长页面分段拼接。
A4 分页图
内容按块分页成同尺寸 A4 截图，表格与图表永不切断，适合打印与耐读。
分享摘要卡
1200×630 结论卡，6 套布局（数据 / 观点 / 头条 / 网格 / 海报 / 步骤），发论坛与微信群。
安装与使用
开始之前
-
1
把 skill 放进 skills 目录
git clone https://github.com/BFRKQSB7/html-guide-skill.git ~/.claude/skills/html-guide目录就位，对话里输入/html-guide可触发。 -
2
按需填 user-config.md
作者署名、代理端口、功能开关都在这个不入库的本地配置里（已被 .gitignore 排除）。
# user-config.md proxy: http://127.0.0.1:<代理端口> author: BFRKQSB7 theme-toggle: on print-btn: on生成的页面带上你的署名，功能按你的开关裁剪。 -
3
触发生成
直接说「把这段内容做成 HTML」「页面化」，或粘贴内容后加一句要求。内容可以是对话回答、Markdown 笔记、本地文件、网页 URL，或只有一个主题。
把下面这份笔记做成 HTML 指导文档，要能离线打开、能打印： —— 粘贴笔记内容 ——流程开始，会先问你要哪些输出物和哪套风格，再进入核实与撰写。 -
4
拿到成品
交付一个单文件 .html，双击即开；需要时再导 PDF / 长图 / A4 分页 / 摘要卡。
一份可离线打开、可打印、可分享的页面。
进阶：自检与降级机制进阶
交付前跑校验脚本，直到 0 error：
python scripts/check_html.py 输出.html联网核实默认走 WebSearch / WebFetch；两者失效时降级到 browser-testing skill 走真实浏览器采集正文——搜索降级链的完整说明在 search-guide.md[4]。
参考来源
本页内容来自 html-guide 技能自身文件（仓库尚未创建，链接按预期路径占位）：
- html-guide 仓库 — SKILL.md（工作流与硬规则）
- references/design-system.md — 视觉设计体系
- references/structure-guide.md — 文档类型 → 结构映射
- references/search-guide.md — 联网核实与降级链
- scripts/check_html.py — 自检校验脚本