mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-19 15:36:29 +03:00

Files

T

Magnus Hedemark 88e92f4472 feat: add epub skill v2 — 11 scripts, 9 references, 46 tests

Complete EPUB creation, editing, validation, and knowledge extraction
skill for the Agent Skills open format. Built from spec research, real
EPUB testing on 2.1MB commercial Apress title, and Apple Books
compatibility verification on macOS 26.

Scripts (11):
  epub-scaffold    — Create valid EPUB3 with cover XHTML, Apple Books CSS
  epub-edit        — Surgical editing (8 subcommands, epublib)
  epub-info        — Structure/metadata dump as JSON
  epub-text        — Clean text extraction, per-chapter or single-file
  epub-extract-knowledge — Heuristic + LLM extraction (env var auto-detect)
  epub-validate    — EPUBCheck or Python fallback validation
  epub-images      — List/extract all images with cover detection
  epub-batch       — Multi-file processing (extract-text, validate, metadata)
  epub-convert     — EPUB2→EPUB3 conversion with validation
  epub-repair      — Diagnose & auto-fix common structural issues
  epub-cover       — Add cover XHTML wrapper for Apple Books compatibility

References (9):
  epub-format-internals.md, python-libraries.md, spec-and-validation.md,
  tutorials-and-guides.md, agent-capability-discovery.md,
  fixed-layout-epub.md, accessibility.md, media-overlays.md,
  apple-books-compatibility.md (NEW — verified on macOS 26)

Test: 46/46 passing (test_epub_skill.sh)

2026-05-23 18:08:48 -04:00

2.8 KiB

Raw Blame History

Fixed-Layout EPUB

Fixed-layout EPUBs predefine page dimensions and element positioning, unlike reflowable EPUBs where content adapts to the reading system's viewport. They're common in children's books, comics, manga, and heavily designed publications where layout integrity matters.

Detection

A fixed-layout EPUB declares layout properties in the OPF <metadata> or <manifest> section. Look for these signals:

Package-level declaration

<meta property="rendition:layout">pre-paginated</meta>

Spine-level declaration

<itemref idref="page1" properties="rendition:layout-pre-paginated"/>

Manifest-level declaration

<item id="page1" href="page1.xhtml" media-type="application/xhtml+xml"
      properties="rendition:layout-pre-paginated"/>

Key rendition properties

Property	Values	Purpose
`rendition:layout`	`reflowable` (default), `pre-paginated`	Whether content adapts or is fixed
`rendition:orientation`	`auto` (default), `landscape`, `portrait`	Preferred reading orientation
`rendition:spread`	`auto`, `both`, `none`, `landscape`	How pages display: single or spread

Dimensions

Fixed-layout pages specify their viewport dimensions:

<meta name="viewport" content="width=768, height=1024"/>

Reading systems use this to set the initial containing block. If missing, reading systems may infer dimensions from the first page's content or fall back to device defaults.

Why Fixed-Layout Matters for Scripts

Our EPUB skill is reflowable-first. When processing a fixed-layout EPUB:

Text extraction will work but paragraph boundaries may be odd — each page is a separate XHTML document with absolute-positioned elements.
Knowledge extraction should still work since it operates on extracted text regardless of layout.
epub-edit may produce unexpected results — adding chapters, reordering spine, or injecting CSS assumes reflowable document structure.
epub-convert does NOT convert fixed-layout to reflowable (out of scope).

Detection in `epub-info`

epub-info reports "fixed_layout": true/false when rendition:layout is detected in the package metadata or on spine items.

Authoring Constraints

When creating fixed-layout EPUBs:

Each page is typically a separate XHTML document
CSS position: absolute is used for element placement
Images are often the page background with text overlaid
Font sizing is in px or pt, not relative units
Navigation must still be provided (NAV document)
Media overlays (SMIL) are often used for read-aloud

References

W3C EPUB 3.3 §8 Fixed Layouts: https://www.w3.org/TR/epub-33/#sec-fixed-layouts
W3C EPUB 3.3 §8.1.3 Viewport Rendering: https://www.w3.org/TR/epub-rs-33/#sec-fxl-viewport

2.8 KiB Raw Blame History