# Can book-to-skill Handle Image-Rich EPUBs? A Deep Dive into the Parser

> Explore if book-to-skill handles image-rich EPUBs. Discover why this text-only extractor doesn't embed images and what its current limitations are.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: deep-dive
- Published: 2026-08-27

---

**No—book-to-skill is a text-only extractor that detects images but does not extract or embed them in the generated skill output.**

The `book-to-skill` repository provides deterministic EPUB parsing for creating structured skills, but its architecture explicitly excludes binary resource handling. According to the source code in `virgiliojr94/book-to-skill`, the EPUB parser processes XHTML content for textual narrative while flagging—not processing—embedded images.

## How the EPUB Parser Handles Image Content

The core parsing logic resides in [`book_to_skill/parsers/epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/epub.py). When processing an EPUB archive, the parser walks through XHTML documents and applies a **text-first extraction strategy**.

### Image Detection Without Extraction

The parser identifies `<img>` tags during traversal and sets an internal flag, but it never extracts the actual image files from the EPUB container:

```python
from book_to_skill.parsers.epub import EPUBParser

parser = EPUBParser("image-heavy-book.epub")
parser.parse()

# The parser records image presence but returns no image data

print("Images present:", parser.has_images)  # → True

print("Image count:", parser.image_count)    # → Number of <img> tags found

```

This design choice reflects the tool's deterministic philosophy: **reproducible text output** takes precedence over multimedia fidelity.

## Extracting Skills from Image-Rich EPUBs

The high-level `extract()` function follows the same text-only pattern. Any visual content in the source EPUB is intentionally omitted:

```python
from book_to_skill import extract

# EPUB with diagrams, photos, or illustrations

epub_path = "technical-manual.epub"

skill = extract(epub_path)

# Output contains structured text only

print(skill.content)        # Plain-text narrative

print(skill.metadata)       # Contains "contains_images": True

```

The generated skill follows the schema defined in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), which specifies **no image fields** in the output structure.

## Verifying Image Reporting Behavior

The test suite confirms this limitation. Run the dedicated image-reporting test to observe the parser's behavior:

```bash
pytest tests/test_epub_image_reporting.py -v

```

This test validates that:
- `has_images` is set to `True` when `<img>` tags are encountered
- No image binary data is returned in the parse result
- Image file paths from `src` attributes are logged but not resolved

## Why Images Are Excluded

The architectural decision stems from [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md), which positions `book-to-skill` as a **deterministic text extractor** optimized for downstream language model consumption. Key constraints include:

- **Determinism**: Binary extraction would introduce variability based on image formats and encoding
- **Schema simplicity**: The skill format prioritizes searchable, token-efficient text
- **Scope boundary**: Image handling would require additional dependencies (PIL, image hash libraries) and storage infrastructure

## Workarounds for Image-Rich Sources

If your workflow requires visual content from EPUBs, you must extend the parser manually:

1. **Extract images separately** using `zipfile` or `ebooklib` to pull resources from the EPUB's `OEBPS/Images/` directory
2. **Store images externally** in a media folder with deterministic naming (e.g., hash-based filenames)
3. **Reference images in skill markup** by extending the skill schema to include image URLs or base64 data
4. **Use alt text fallback** where the parser already captures `alt` attributes from `<img>` tags into the text stream

## Summary

- **book-to-skill detects images** via `has_images` flag in `EPUBParser` but does not extract them
- **Generated skills contain only text**, following the schema in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) with no image fields
- **The parser source** at [`book_to_skill/parsers/epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/epub.py) shows explicit exclusion of binary resource handling
- **Extension required**: Image support demands custom modifications to both parser and skill schema

## Frequently Asked Questions

### Does book-to-skill extract alt text from images?

Yes. When the parser encounters `<img alt="description">` tags, the **alt attribute text is included** in the extracted content stream as plain text. This preserves descriptive context even when the visual asset is discarded.

### Can I modify book-to-skill to include images in skills?

Yes, but it requires substantive changes. You would need to extend `EPUBParser.parse()` to extract binary resources from the EPUB zip structure, modify the skill schema in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) to accommodate image references, and update serialization logic. No plugin hooks exist for this currently.

### What happens to EPUBs where images contain critical information?

The **text-only output will be incomplete** for such sources. Diagram captions, figure references, and surrounding textual context are preserved, but visual data (charts, photographs, illustrations) is lost. Evaluate source material before processing; image-dense textbooks may need alternative extraction pipelines.

### Is there a configuration flag to enable image extraction?

**No.** The `extract()` function and `EPUBParser` class expose no parameters for image handling. This is architectural, not configurable—the deterministic text focus is embedded in the design principles documented in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md).