diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 23 |
1 files changed, 21 insertions, 2 deletions
@@ -17,8 +17,8 @@ Four decoupled concerns, each a small module that does one thing: | ------------- | --------------------------------------------------------- | | `index.zig` | discover versions + docs URLs from `download/index.json` | | `fetch.zig` | HTTP GET via `std.http.Client` | -| `html.zig` | transform the page HTML5 → well-formed XHTML5 | -| `epub.zig` | assemble the EPUB3 container | +| `html.zig` | HTML5 → XHTML5; extract the in-page TOC; drop the sidebar | +| `epub.zig` | assemble the EPUB3 container (TOC navigation + content) | | `zip.zig` | minimal, reproducible ZIP writer (stored entries) | No external runtime dependencies — Zig's standard library provides HTTP and @@ -28,6 +28,25 @@ spec-compliant at the cost of larger files. Output is **byte-for-byte reproducible** (fixed ZIP timestamps), so CI only commits when the upstream docs actually change. +### Table of contents + +The docs page renders its table of contents in a `position: fixed` sidebar, which +e-readers repaint on every page. The tool extracts that TOC into a proper EPUB3 +navigation document (`nav.xhtml`): it shows in the reader's built-in Contents +menu, is the book's opening page, and each entry jumps to the matching section. +The original fixed sidebar (and its dead version-switcher dropdown) is removed +from the content so it no longer bleeds across pages. + +### Well-formedness gate + +Each transformed page is checked for well-formed, balanced XHTML before +packaging; versions that fail are **skipped** (logged as `NotWellFormed`) rather +than shipped as invalid EPUB3. A handful of older docs pages (currently 0.1.1–0.8.1 +and 0.10.x) contain malformed upstream HTML — unclosed `<p>`/`<li>` tags and +outright typos — that can't be repaired without a full HTML5 tree-builder. Every +EPUB this tool produces is therefore strictly well-formed; newer versions are +picked up automatically as they are released. + ## Usage Requires **Zig 0.15.2**. |