HTML 文档
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md 安装 @user_088367b5/docs-html。
技能介绍
为什么要单文件 HTML
架构图、API 手册和 Runbook 散落在多个 Markdown 里,复制给别人时图片链接经常失效。传统的文档站点需要 Jekyll 或 Node 环境,代码审查工具也只展示平铺文本,阅读体验缺乏导航感。生成自包含的 .html 文件可以解决这些问题——读者浏览器打开即用,跳过依赖安装和编译步骤。
技能如何处理文档
- 模板驱动:基于
assets/template.html构建,直接复用内置的两栏响应式布局、暗色模式和阅读进度条。 - Material 分类:自动提取 Markdown 标题、代码块和跨文档引用,按 Overview → TOC → Body → References 的逻辑重组结构。
- 零依赖渲染:表格、提示框和目录滚动监听(Scroll-spy)均由原生 CSS/JS 驱动,不依赖外部网络请求。
- 交叉引用:支持
href="#section-id"形式的锚点链接,方便在不同章节间跳转。
适用边界与注意点
默认构建会将内容锁定在一份静态文件中,不支持多人实时协同编辑。生成大体积文档时,浏览器的单次内存加载可能遇到瓶颈。
如果需要复杂的时序图或依赖图,脚本会从 CDN 拉取 mermaid.js;一旦用户处于离线环境,部分图表将无法渲染,但在仅查看其他文本和小尺寸流程图时是可行的。
使用场景
- 整理架构说明、API 参考和 Runbook 等多份 Markdown,需要合并成一个带目录导航与深浅色主题的 HTML 页面,便于直接分享。
- 写完 API 文档后,要把参数说明和示例代码排版成参数表格与代码块,并支持锚点跳转,生成无需服务端渲染的 HTML。
- 给新人做代码 walkthrough,要把模块解读发成一个 HTML,对方打开即读,无需装环境,窄屏手机上也看得清楚。
- 把运维 Runbook 转成离线可读的 HTML 文件发到群里,读者双击就能看,进度条、暗色模式和小尺寸流程图仍能正常显示。
适合人员
- 后端/平台工程师:常写 API 参考与架构说明,想把多份文档合并成一个可分享、可检索的 HTML,方便评审与沉淀。
- 技术文档作者:要把设计文档和手册发成可直接打开的成品页面,不想维护构建脚本和部署环境。
- SRE/运维工程师:希望把 Runbook 做成离线可读、窄屏也能看清的 HTML 文件,临时排查时随手就能翻。
- 技术负责人/布道师:想把模块解读整理成带图表的单页讲义,在分享会或代码 walkthrough 中发到群里直接看。