4.7 KiB
name, description
| name | description |
|---|---|
| html-doc | 生成人类可读的单文件 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。
提示框：
<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 发回 → 作者打开即见。纯前端、零依赖、幂等。
接入三步：
<body data-note-ns="文档唯一标识">（骨架已留{{DOC_ID}}；隔离不同文档的本地暂存）- 标记批注目标（二选一或混用）：
- 表格模式：
<table data-annotate="唯一名">→ 每行自动追加一列「备注」 - 区块模式：任意元素加
data-note-id="唯一名"→ 其后插入一个备注框 - 防行序漂移：可给某
<tr>加data-note-id="稳定key"覆盖自动 key
- 表格模式：
- 把
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-notesJSON —— 由模块导出维护。 - 中文文本别用 PowerShell
Set-Content/echo >落盘（GBK 会损坏），用文件工具写。
自迭代日志
本节记录使用本 Skill 过程中发现的必要检查项。
已知必要检查
- 单文件自包含 — 生成后确认
theme.css（及批注时的annotate.js）已真正内联，页面无<link>/外链<script src>，否则发给别人会样式/功能丢失。 - 批注命名空间唯一 —
data-note-ns必须每份文档不同，否则不同文档的 localStorage 暂存互相污染。