89 lines
4.7 KiB
Markdown
89 lines
4.7 KiB
Markdown
---
|
||
name: html-doc
|
||
description: >-
|
||
生成人类可读的单文件 HTML 文档（参考手册、报告、字段说明、清单等），统一深色主题
|
||
与版式（侧边目录 + 表格 + callout + 徽标 + 代码块），并可选挂载标准化的「批注模块」——
|
||
让读者逐字段/逐区块填备注、自动暂存、一键导出带备注的 HTML 副本回传，作者打开即见全部批注。
|
||
当用户要「做一份给人看的 HTML 文档/参考手册/说明页/报告」，或提到「统一 HTML 样式」、
|
||
「让别人写批注/注释」、「可批注文档」时使用。
|
||
---
|
||
|
||
# html-doc
|
||
|
||
把「给人阅读的 HTML 文档」标准化：统一主题 + 统一版式 + 可选批注模块。**产出单文件自包含 HTML**（CSS/JS 全内联，一个 `.html` 直接发人）。
|
||
|
||
## 资产
|
||
|
||
| 文件 | 作用 | 生成时怎么用 |
|
||
|------|------|------|
|
||
| `assets/theme.css` | 通用深色主题（tokens + 版式 + 表格/callout/徽标/目录/代码块） | 内联进 `<head><style>` |
|
||
| `assets/annotate.js` | 标准化批注模块（表格列 / 区块框、localStorage 暂存、导出嵌 JSON、复制 Markdown） | 需批注时内联进末尾 `<script>` |
|
||
| `templates/skeleton.html` | 文档骨架（侧栏目录 + 正文 + 占位符） | 复制后填内容 |
|
||
|
||
> 三者是唯一真相源；改主题/批注逻辑只改 assets，再重新生成文档。
|
||
|
||
## 生成工作流
|
||
|
||
```
|
||
1. 明确文档类型与章节结构（参考手册 / 报告 / 清单…）
|
||
2. 复制 templates/skeleton.html，替换占位符：
|
||
{{TITLE}} {{SUBTITLE}} {{DOC_ID}}（批注命名空间，用短横线英文，如 csv-data-reference）
|
||
{{TOC_LINKS}} {{CONTENT}} {{FOOTER}}
|
||
3. 把 assets/theme.css 全部内容内联到 <head> 的 <style> 里（单文件自包含）
|
||
4. 按「组件速查」填正文；每章一个 <section id="...">，与目录 <a href="#..."> 对应
|
||
5. 若需批注 → 见「批注模块」：给目标加 data 属性 + 内联 annotate.js
|
||
6. 用 Read/ReadLints 自查；中文内容务必用文件工具写（勿用 PowerShell 重定向，见 baserule）
|
||
```
|
||
|
||
## 组件速查
|
||
|
||
章节标题：`<h2 class="section">`（自带顶部分隔线）；子标题 `<h3>`。
|
||
|
||
目录项：`<a href="#id">主名<span class="cn">副名</span></a>`；分隔 `<div class="sep"></div>`。
|
||
|
||
表格：标准 `<table><thead><tr><th>…</thead><tbody>…`。类型列用 `<td class="type">`。
|
||
|
||
徽标（语义色，放 `<span class="badge X">`）：`accent` / `ok` / `warn` / `danger` / `muted`。
|
||
|
||
提示框：
|
||
```html
|
||
<div class="callout warn"><div class="t">标题</div><p>正文</p></div>
|
||
```
|
||
变体：默认（蓝）/ `warn` / `danger` / `ok`。
|
||
|
||
其他：`.tag`（等宽 pill）、`.legend`（图例行）、`ul.tight`（紧凑列表）、`.muted`（弱化文字）、`<footer>`。
|
||
|
||
配色改动只动 `theme.css` 的 `:root` design tokens。文档专属徽标追加在内联 theme 之后。
|
||
|
||
## 批注模块（可选）
|
||
|
||
目的：读者填备注 → 导出带备注的 HTML 发回 → 作者打开即见。纯前端、零依赖、幂等。
|
||
|
||
**接入三步**：
|
||
1. `<body data-note-ns="文档唯一标识">`（骨架已留 `{{DOC_ID}}`；隔离不同文档的本地暂存）
|
||
2. 标记批注目标（二选一或混用）：
|
||
- 表格模式：`<table data-annotate="唯一名">` → 每行自动追加一列「备注」
|
||
- 区块模式：任意元素加 `data-note-id="唯一名"` → 其后插入一个备注框
|
||
- 防行序漂移：可给某 `<tr>` 加 `data-note-id="稳定key"` 覆盖自动 key
|
||
3. 把 `assets/annotate.js` 全部内容内联进末尾 `<script>`
|
||
|
||
**运行行为**：页头下方出现工具栏（导出带备注副本 / 复制 Markdown / 清空 / 已填计数）；输入自动存 localStorage；导出时克隆文档、剔除注入 UI、仅把备注以 `<script id="embedded-notes" type="application/json">` 嵌入 → 对方打开由脚本幂等重建并回填。
|
||
|
||
**恢复优先级**：嵌入 JSON > localStorage（保证收到的回传文件一定显示对方批注）。
|
||
|
||
## 反模式
|
||
|
||
- 别用外链 CSS/JS（破坏「一个文件发人」）——一律内联。
|
||
- 别硬编码猜测批注目标（如靠表头文字）——用 `data-annotate` / `data-note-id` 显式 opt-in。
|
||
- 别手改 `embedded-notes` JSON —— 由模块导出维护。
|
||
- 中文文本别用 PowerShell `Set-Content`/`echo >` 落盘（GBK 会损坏），用文件工具写。
|
||
|
||
## 自迭代日志
|
||
|
||
本节记录使用本 Skill 过程中发现的必要检查项。
|
||
|
||
### 已知必要检查
|
||
|
||
1. **单文件自包含** — 生成后确认 `theme.css`（及批注时的 `annotate.js`）已真正内联，页面无 `<link>`/外链 `<script src>`，否则发给别人会样式/功能丢失。
|
||
2. **批注命名空间唯一** — `data-note-ns` 必须每份文档不同，否则不同文档的 localStorage 暂存互相污染。
|