html-anything 技术文档页（docs-page）技能解析：用 Agent 一键生成三栏式 API 文档页

• AI 应用
• 人工智能
• AI Agent
• AI 写作
• 媒体生成

本文围绕 html-anything 开源仓库内置的docs-page模板技能展开，剖析其SKILL.md定义的“侧导航 + 正文 + 右 TOC”三栏文档页设计规范，并结合仓库源码说明技能注册、Prompt 组装与示例渲染的完整调用链。读完本文，你将掌握 docs-page 技能的完整元数据、布局与设计细节，并能将其复用到自己的 API / 教程文档生成场景。

一、docs-page：仓库 75 个模板技能中的文档页专属模板

在 html-anything 中，每个内置模板（Skill）都是一个独立文件夹，位于 next/src/lib/templates/skills/ 下，文件夹内由SKILL.md（必选）、example.md（可选）与example.html（可选）组成。docs-page正是其中之一，其核心定义文件是 next/src/lib/templates/skills/docs-page/SKILL.md。

该文件的 YAML frontmatter 完整记录了技能的注册元数据：

从源码看，这套 frontmatter 由 next/src/lib/templates/loader.ts 中的parseFrontmatter函数解析（支持字符串、整数与["a", "b"]形式的单行数组字面量），再经fmToMeta映射为SkillMeta，最终通过 next/src/app/api/templates/route.ts 的GET /api/templates以{ templates: SkillMeta[] }形式返回给前端选择器。scenario: engineering对应 next/src/lib/templates/scenarios.ts 中的SCENARIO_KEYS之一，会在模板选择器中以“工程”标签分组展示。

二、设计意图：API / 教程文档单页，长读体验优先

SKILL.md正文第一部分明确了该模板的意图：

【意图】API / 教程文档单页, 长读体验优先。

这是 docs-page 区别于 deck、poster、card 等其他技能的根本出发点：它不为短促的视觉冲击服务，而是为持续数分钟到数十分钟的深度阅读设计。因此整个 Prompt 的约束都围绕“信息可扫读、结构可导航、代码可复制”三个目标展开，最终由 Agent 生成一份自包含的单文件 HTML。

需要强调的是，docs-page 只约束版式、风格与组件，不约束章节数量。仓库内置的全局设计指令（见下文第五节）明确要求内容数量完全由用户输入的实际长度决定——写 12k 字符的文档内容时，只输出 4-6 个章节是严重错误。换言之，长文档就该长页输出，页面高度随内容增长，这正是“长读体验优先”的落地方式。

三、布局骨架：三栏 Grid 与两个 sticky 面板

SKILL.md定义了四个布局区域：

1. Inline-start nav（侧导航）：左侧栏目，按分组列出文档章节，支持 sticky 吸顶；
2. Article body（正文）：中间主列，承载代码块、callout、表格等富文档元素；
3. Inline-end TOC（右侧目录）：粘性定位，支持 scroll-spy 滚动高亮；
4. 顶栏：搜索框 + 版本切换 + 主题切换。

仓库自带的可运行示例 next/src/lib/templates/skills/docs-page/example.html 提供了这套骨架的最小实现。其核心是grid-template-columns: 240px minmax(0, 1fr) 220px的三栏布局，并带两级响应式降级：

.layout { display: grid; grid-template-columns: 240px minmax(0, 1fr) 220px; gap: 0; min-height: calc(100vh - 50px); } @media (max-width: 1024px) { .layout { grid-template-columns: 220px 1fr; } .toc { display: none; } } @media (max-width: 720px) { .layout { grid-template-columns: 1fr; } .sidebar { display: none; } }

• 在1024px 以下隐藏右栏 TOC，保留侧导航 + 正文；
• 在720px 以下隐藏侧导航，退化为单列纯阅读模式。

侧导航在示例中用.sidebar+.group-label实现分组标题（如 “Getting started”“Sync engine”“CLI”），当前章节通过.active类高亮（background: var(--accent); color: white），并设置overflow-y: auto让分组菜单自身可滚动。右侧 TOC 使用.toc a.active标注当前阅读位置——这正是SKILL.md中 “sticky, scroll-spy” 的视觉呈现。

四、顶栏与文档正文的关键设计细节

SKILL.md的【设计细节】是整份模板的技术核心，共两条：

4.1 代码块：圆角 + dark + 语言标签 + 复制按钮

代码块是文档页出现频率最高的元素，docs-page 要求其具备四个特征：

• 圆角：示例中为border-radius: 8px；
• dark 深色背景：与正文浅色背景形成强对比，示例用var(--code-bg)深色面板承载pre code；
• 语言标签：在代码块左上角标注语言名（如bash/python）；
• 复制按钮：右上角提供一键复制，降低读者手动选取代码的成本。

示例 HTML 中的实现要点是pre设置overflow-x: auto保证长行可横向滚动，pre code清除继承背景避免双重底色。Agent 按此规范输出代码块时，还需要为每个块标注正确的语言类名，以便前端或阅读器渲染语法高亮。

4.2 callout：info / warn / danger 三色

文档中需要区分提示等级的内容统一用 callout 呈现，SKILL.md规定三色体系：

• info：普通补充说明（示例中label为 “Note”，左边框使用主题色）；
• warn：警告，提醒可能踩坑的操作；
• danger：危险，标注会导致数据丢失或破坏性后果的操作。

示例中的 CSS 实现为：白底、1px边框、左侧3px主题色竖条（border-left: 3px solid var(--accent)）、圆角8px，内部用小号大写字母标签区分类型：

.callout { background: var(--surface); border: 1px solid var(--border); border-left: 3px solid var(--accent); border-radius: 8px; padding: 14px 18px; margin: 20px 0; font-size: 14px; } .callout .label { font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--accent); margin-bottom: 4px; }

正文区还保留了文档页常见的面包屑（.crumbs，如Docs › Getting started › Quickstart）、引导段（.lede）与底部翻页器（.pager，Previous / Next 链接）——这些虽未逐条写进SKILL.md，但出现在示例实现中，是文档页长读体验的完整组成部分。

五、从 SKILL.md 到成品：Prompt 组装与渲染链路

docs-page 的SKILL.md正文是一段面向 Agent 的中文指令，但它并不会被直接发给模型。仓库中组装最终 Prompt 的规范化流程如下：

1. 读取技能：next/src/app/api/convert/route.ts 的POST /api/convert接收{ agent, templateId, content, format }，通过loadSkill(templateId)从磁盘读取SKILL.md，解析出 frontmatter 与正文 body；
2. 拼接全局指令：assemblePrompt({ body, content, format })把技能的 body 包裹进一份全局共享设计指令中。全局指令定义在 next/src/lib/templates/shared.ts（CLI 侧的同构版本见 cli/src/prompt-assemble.ts），包含内容驱动数量、禁止使用文件系统工具、纯 HTML 流式输出、CDN 引入 Tailwind 与字体、1 主色 + 2 中性色 + 至多 1 强调色、8px 基线网格、对比度 ≥ 4.5 等硬性要求；
3. 流式返回：invokeAgent调用本地 CLI Agent（Claude Code / Cursor / Codex / Gemini 等）生成 HTML，/api/convert以 SSE（text/event-stream）流式转发；
4. HTML 提取：next/src/lib/extract-html.ts 的extractHtml负责从 Agent 可能夹杂解释性文字的回复中剥离出<!DOCTYPE html> ... </html>完整文档，previewHtml则在流式过程中补全闭合标签以便 iframe 增量渲染。

也就是说，docs-page 的SKILL.md正文只需定义“长什么样、有哪些组件、什么配色气质”，其余技术红线由SHARED_DESIGN_DIRECTIVES统一兜底——这与仓库 next/src/lib/templates/index.ts 中 “Adding a new template = adding a new folder with SKILL.md” 的扩展模型完全一致：新增技能无需改动任何 TS 代码。

六、示例内容与预览机制

docs-page 的文件夹结构如下：

next/src/lib/templates/skills/docs-page/ ├── SKILL.md # 技能元数据 + Prompt 正文 └── example.html # 预渲染示例（本技能无 example.md）

与部分技能同时附带example.md（示例输入内容）不同，docs-page 仅附带example.html，演示了一个虚构的 “Filebase docs” Quickstart 页面：包含顶栏搜索（placeholder 为Search · ⌘K）、三组侧导航、带语言标签和复制按钮的代码块、Note 型 callout、四段式 TOC 与底部 pager。

该示例通过 next/src/app/api/templates/[id]/example/route.ts 的GET /api/templates/docs-page/example暴露，返回{ id, name, templateId, format, tagline, desc, source, content, html }的 JSON 包，前端可直接注入loadSample()用于模板选择器的 “Preview” 预览；loader.ts中的skillHasPreview则通过检查example.html是否存在，决定选择器是否显示预览入口。

七、实战建议：如何把 docs-page 用于自己的文档

要在 html-anything 中生成技术文档页，实际操作路径是：

1. 在模板选择器（或直接以docs-page作为templateId）选中“技术文档页”技能；
2. 把 API 参考、教程正文等原始内容粘贴进编辑器（支持 Markdown、纯文本等格式，format字段会原样传给assemblePrompt标注输入格式）；
3. 点击转换，等待 Agent 流式输出，前端自动完成 HTML 提取、沙箱预览与导出（HTML / PNG / 各平台一键分发）。

在 AI 提示词层面，你也可以直接复用SKILL.md的正文结构——只要在给模型的指令中显式列出三栏布局、sticky 行为、代码块四要素与 callout 三色，就能在其他对话式 Agent 中复现同款文档页。建议结合仓库中的示例文件对照阅读：SKILL.md 原文 定义了“做什么”，example.html 展示了“长什么样”，两者结合即是完整的可执行规范。

• AI 应用
• 人工智能
• AI Agent
• AI 写作
• 媒体生成