# HTML Use
> Use when content should be delivered as a local HTML artifact instead of plain markdown, especially when it needs a collapsible left sidebar navigation, calm reading-oriented styling, and must be saved under the project's html directory
- Skill: `lucianwhy/html-use` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lucianwhy/html-use`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucianwhy/html-use/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: lucianwhy (https://skillmd.com/u/lucianwhy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lucianwhy/html-use
---
# HTML Use
## Overview
把内容做成可直接打开的 HTML 成品，不停留在聊天排版。
核心原则：
- 文件必须落到项目 `html/`
- 页面必须有左侧可收缩导航
- 样式要偏“安静、清晰、可长时间阅读”
- 视觉重点服务信息结构，不做花哨装饰
## When to Use
适合：
- 用户明确要 `HTML` 展示
- 内容较长，需要导航定位
- 需要交付本地文件而不是聊天临时文本
- 需要把说明、总结、方案、复盘做成可复用页面
不要用在：
- 用户只要短回答
- 用户明确要求 Markdown / 纯文本
- 只是内部草稿，还不需要 HTML 成品
## Output Location
HTML 文件统一放到当前项目下的：
```text
html/
```
规则：
- 如果 `html/` 不存在，先创建
- 文件名必须和主题切题
- 默认使用 `.html` 后缀
命名示例：
- `payment-architecture-map.html`
- `bug-retro-summary.html`
- `feature-scope-review.html`
## Required Layout
每个 HTML 产物都必须满足：
- 页面含左侧侧边栏
- 侧边栏用于导航锚点跳转
- 侧边栏支持收缩 / 展开
- 主内容区滚动阅读
根结构建议：
```html
...
```
## Visual Direction
默认风格不是“产品后台蓝白卡片”，而是“阅读型技术说明页”：
- 背景：暖白 / 米白
- 标题：衬线字体，拉开层级
- 正文：无衬线字体，保证长文易读
- 路径 / 文件 / 代码：等宽字体
- 强调色：陶土 / 橄榄 / 深灰，少量使用
- 卡片与边框：轻，不要厚重投影堆叠
目标感觉：
- 像高质量技术备忘录
- 像架构 walkthrough
- 不像营销页
- 不像花哨仪表盘
## Recommended Information Blocks
长内容优先拆成这些块，而不是一整页散文：
- `header / summary`
- `diagram / flow`
- `step walkthrough`
- `key files`
- `gotchas / red flags`
- `acceptance / next step`
如果内容是总结类、方案类、复盘类，这套块结构优先于随意排版。
## Minimal Template
```html
页面标题
```
## Workflow
1. 确认输出主题
2. 创建项目下 `html/`
3. 起一个主题明确的文件名
4. 先搭“左侧导航 + 右侧主内容”骨架
5. 再填 `summary / steps / files / risks` 等信息块
6. 加入导航收缩脚本
7. 本地检查导航、滚动、收缩、窄屏阅读
## Quick Reference
- 导航栏：左侧 `aside`
- 内容区：右侧 `main`
- 导航方式：锚点 `href="#section-id"`
- 收缩状态：给外层容器切 `is-collapsed`
- 标题：优先 serif
- 正文：优先 sans
- 路径 / 代码：优先 mono
- 输出目录：项目 `html/`
## Common Mistakes
- 只把 Markdown 搬进 HTML，不重做信息层次
- 用蓝白后台卡片味太重，阅读感太差
- 有导航栏，但不能收缩
- 把 HTML 丢到别的目录
- 文件名太泛，后续找不到
- 页面只适配桌面，不处理窄屏
- 视觉太花，盖过内容本身
## Verification
交付前至少确认：
- `html/` 目录存在
- HTML 文件能直接双击或浏览器打开
- 左侧导航点击可跳转
- 导航栏可收起、可展开
- 窄屏下内容不挤爆
- 标题 / 正文 / 代码层次清楚
- 页面整体更像“阅读型技术说明页”，不是营销页