图书转换学习手册 (Book to Study Manual)

Build a fully static HTML+CSS+vanilla-JS site that works by double-clicking index.html
(file://) or being hosted on any static server, with zero dependencies, zero build, and
zero SVG. The architecture generalizes to any book, textbook, or study material organized as
a chapter/section/leaf structure (or any nested outline of topics).

Hard constraints (enforce from the start)

• Zero dependencies / zero build. Only HTML, CSS, and vanilla JS. No npm, no bundler,
  no CDN. All script tags are local files. Works under the file protocol by double-click.
• No SVG anywhere. No svg tags, no .svg files, no css svg urls. Use CSS shapes
  (gradients, border-radius, box-shadow), Unicode glyphs (★ ● ◆ ✚ → ↑), and bitmap
  illustrations (.jpg/.png). Verify with grep: search for "svg" across the tree and expect nothing.
• Bitmaps only for illustrations. AI-generated or public-domain realistic photos;
  never AI-generated human portraits (use metaphor objects instead). Keep per image small
  (resize width ~720, quality ~62) to stay within any subpackage size limits.
• Images are optional. A fully image-free variant is supported — see §无图片版本 below.
  In that mode assets/img/ is dropped and <img> tags are stripped, but all navigation / search / export still work.
• Offline search must not use fetch. fetch() is blocked under file:// (CORS).
  Build the search index at build time into a JS file (window.MANUAL_SEARCH) and match with
  local indexOf/RegExp. See references/architecture.md.
• PDF export goes through the print dialog. A zero-dependency static site cannot
  generate a real .pdf file directly. The "另存为 PDF" path is window.print() with a
  @media print stylesheet that hides toolbars and paginates; the user picks "另存为 PDF"
  as the print destination. Label buttons "另存为 PDF", never "打印".

File layout

index.html              # catalog home (3-level collapse, progress, search box)
c1-1-1.html ...         # one file per "leaf" node (chapter-section-leaf), + intro-N.html
assets/main.css         # design tokens + all component styles
assets/nav.js           # CATALOG data + catalog/search/export/progress logic (window.Manual)
assets/search-data.js   # build-time full-text index (window.MANUAL_SEARCH)
assets/img/*.jpg        # one realistic illustration per page (+ cover.jpg)
print/(chapter).html    # per-chapter print page (intro/c1..c7)
print/full.html         # whole book (all leaves inlined)
print/picker.html       # multi-page picker (checkbox per leaf)

Build generators live in /tmp/ (never in the site) and emit search-data.js and the
print/ pages from nav.js + the content pages. See references/architecture.md.

Workflow

1. Lock the structure

Confirm the source outline (chapters → sections → leaves) and the count of leaf nodes
(EXPECTED). Drive every page filename and the catalog from one CATALOG array so there
are zero 404s. Define a strict per-page module order (e.g. 结论 → 白话 → 案例 → 术语 →
自检题) and a word budget per module before generating pages.

2. Scaffold index + one sample page (lock the look)

Build index.html, main.css (design tokens first), and nav.js with the catalog +
navigation. Generate ONE sample content page, get the visual signed off, then batch the rest
with the same template. Keep class names stable so later CSS edits don't break pages.

3. Generate the leaf pages

Batch the remaining pages. For each: Manual.initPage(id, returnTargetUrl) renders breadcrumb +
prev/next pager + marks read. Keep initPage(id) identical to the CATALOG leaf id.

4. Offline full-text search

Generate assets/search-data.js at build time: for each leaf, store
{id,title,chapter,section,conclusion,fulltext} (fulltext = stripped main.page inner text).
On every page inject a search box + results container and load search-data.js
before nav.js; call initSearch() from initPage. Match title+chapter+section+fulltext
with AND multi-term, highlight with mark tags, show a snippet around the first hit. Empty query
restores the catalog tree.

5. PDF export (chapter / picker / full)

Generate print/ pages that inline each leaf's main body. Print pages carry a
.no-print toolbar with a 📄 另存为 PDF button calling window.print(). @media print
hides .no-print, paginates each leaf (page-break-after: always), and expands answers.
picker.html adds a checkbox per leaf + pickExport() that hides un-checked blocks then
prints. Wire a top-bar details.export-wrap dropdown (导出本章 / 自选多页 / 导出整本)
and matching home-page entry buttons.

6. Polish & known bugs (fix proactively)

• Catalog won't re-open after Return: never re-bind click listeners on re-render.
  Bind catalog events ONCE in initIndex after the first renderCatalog; let
  expandAncestors/expandAll/collapseAll re-render without re-binding.
• Fixed progress label overlaps content: give body { padding-top: 38px } so the
  fixed progress bar + label float in reserved space; add white-space: nowrap to the label.
• Dropdown menu stays open / blocks clicks: close details.export-wrap on outside click,
  Escape, and on menu-link click (see closeExportMenus in references/architecture.md).
• Search results container hidden by display:flex: add .search-results[hidden]{display:none!important}
  and toggle visibility via style.display, not just the hidden attribute.

7. Build & publish

Copy site files into a clean _publish/ EXCLUDING .workbuddy/, generated-images/, and any
*.bak/img-prompts.md (private). Then deploy with workbuddy_sites_deploy
(directory=_publish, language=static). Re-publishing the same dir reuses the sandbox and
keeps the link stable. Verify index.html, search-data.js, nav.js, main.css, every
print/*.html, and a sample content page return 200.

8. 无图片版本（可选）

有些场景（纯文本离线阅读、低带宽、无障碍、极致轻量）希望去掉所有插图。本 skill 支持在生成完
标准手册后，单独产出一个无图片版本：

• 产出目录：_publish-noimg/（与 _publish/ 结构一致，只是不含 assets/img/）。
• 处理规则（可让 agent 按此规则手工处理，或用 scripts/make_noimg.py）：
  1. 复制整站，排除 assets/img/ 目录。
  2. 删除所有 <img ...> 标签；<figure class="figure"> 内的 <figcaption> 文字保留，
  变成纯文字图注（复用已有 .figure 样式）。
  3. 删除图片相关 meta/link：og:image、apple-touch-icon、rel="icon"、rel="manifest"
  （无图版不需要图标与 manifest）。
  4. CSS / JS / 搜索索引 search-data.js / 打印页 print/ 全部原样保留——搜索、进度、导出 PDF 照常可用。
• 运行：python3 scripts/make_noimg.py --src _publish --dst _publish-noimg
• 部署：对 _publish-noimg/ 单独执行一次 workbuddy_sites_deploy
  （目录不同 → 得到另一个独立链接，不会覆盖有图版）。

Verification checklist

• grep -rn "svg" . returns nothing.
• Leaf file count == EXPECTED == CATALOG leaf id count (zero 404).
• node --check assets/nav.js passes.
• Search: a term known only from body text returns the right pages; snippet sits on the hit.
• Export: each print page opens; window.print() fires from the button; picker hides
  un-checked leaves.
• Progress label + dropdown do not overlap or block content.

See references/architecture.md for the concrete CATALOG schema, nav.js API, search-data
schema, and print-page CSS. Use the flat boilerplate files (index.html, page.html, assets/main.css, assets/nav.js, assets/search-data.js) as a starting scaffold.