# How Book-to-Skill Handles EPUB, DOCX, and HTML Document Formats

> Discover how Book-to-Skill expertly manages EPUB, DOCX, and HTML files. Learn about the specialized parser modules and sanitization pipeline that convert your documents into structured text.

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

---

**Book-to-Skill processes EPUB, DOCX, and HTML files by delegating to dedicated parser modules—[`epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/epub.py), [`docx.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/docx.py), and [`html.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/html.py)—that extract structured text before normalizing it through a shared sanitization pipeline.**

The open-source `virgiliojr94/book-to-skill` repository converts source books into reusable skill definitions through a modular parsing architecture. Each supported file type routes through a specialized extractor that normalizes content into a common `Section` schema, enabling consistent downstream processing regardless of input format.

## Parser Architecture and Orchestration

The entry point for all document processing resides in [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py), which inspects file extensions and dispatches to the appropriate parser. Every parser adheres to a unified interface contract:

```python
def parse(file_path: str) -> List[Section]:
    """Return a list of Section objects (title, body, metadata)."""

```

This standardization allows the system to treat EPUB containers, Word documents, and HTML pages as interchangeable sources of structured content. After extraction, all text flows through [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) for Unicode normalization and control-character removal before skill generation.

## Format-Specific Processing Strategies

### EPUB Processing with `ebooklib`

The EPUB parser at [`book_to_skill/parsers/epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/epub.py) leverages the `ebooklib` library to navigate the container format. It opens the archive, iterates over each spine item representing HTML chapters, and feeds chapter content into the generic HTML extractor.

```python
from book_to_skill.parsers.epub import parse as parse_epub

sections = parse_epub("my_book.epub")
for sec in sections:
    print(sec.title)
    print(sec.body[:200])   # preview first 200 characters

```

The parser collects cleaned chapter text while preserving the document's reading order as defined by the EPUB manifest.

### DOCX Processing with `python-docx`

Microsoft Word documents route through [`book_to_skill/parsers/docx.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/docx.py), which utilizes the `python-docx` library. The implementation loads the `.docx` archive with `Document`, then walks through paragraphs and tables while preserving heading hierarchy.

```python
from book_to_skill.parsers.docx import parse as parse_docx

sections = parse_docx("my_manual.docx")
for sec in sections:
    # Sections already contain heading hierarchy

    print(sec.title, sec.level)   # level corresponds to heading depth

```

The extractor strips styling tags and converts Word's structural elements into the common `Section` representation, maintaining semantic heading levels for downstream skill generation.

### HTML Processing with Standard Library Parsers

Raw HTML files pass through [`book_to_skill/parsers/html.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/html.py), which implements a custom `_HTMLTextExtractor` class extending `HTMLParser` from Python's standard library. This parser tracks block elements such as `<p>` and `<h1>` to preserve document structure while removing scripts, styles, and boilerplate navigation elements.

```python
from book_to_skill.parsers.html import parse as parse_html

sections = parse_html("article.html")
print(sections[0].body)   # whole article body, free of HTML tags

```

The implementation returns plain text sections by filtering non-content tags and collapsing unnecessary whitespace.

## The Shared Sanitization Layer

Regardless of source format, extracted sections undergo processing in [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py). This module normalizes Unicode representations, removes zero-width and bidirectional control characters, and strips annotation sequences that could interfere with LLM prompting.

The sanitization pipeline ensures that EPUB chapters, Word documents, and HTML pages emit deterministic, JSON-compatible representations suitable for the skill generator. Configuration flags governing supported extensions and default parsers reside in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py), allowing the system to extend to additional formats like PDF and RTF through the same interface.

## Summary

- **Modular parsers** in `book_to_skill/parsers/` handle EPUB (`ebooklib`), DOCX (`python-docx`), and HTML (`html.parser`) through a unified `parse()` interface.
- **Format detection** occurs in [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py), which routes files based on extension to the appropriate extractor.
- **Structured extraction** preserves heading hierarchies and chapter order, converting all inputs to a standard `Section` schema containing title, body, and metadata.
- **Universal sanitization** in [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) normalizes Unicode and removes control characters before skill generation.
- **Extensible configuration** in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) defines supported formats for easy addition of new document types.

## Frequently Asked Questions

### How does Book-to-Skill determine which parser to use for a file?

The system inspects the file extension in [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) and maps it to the corresponding parser module defined in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py). This routing mechanism allows seamless addition of new formats by registering new extensions and parser imports without modifying the core extraction logic.

### Can Book-to-Skill handle corrupted or non-standard EPUB files?

The EPUB parser relies on `ebooklib`'s `EpubReader` to open containers. While it follows the standard EPUB specification for spine iteration, severely malformed archives may raise exceptions at the library level. The current implementation does not include repair logic for corrupted ZIP structures or invalid XML manifests.

### What structural information is preserved when parsing DOCX files?

The DOCX parser extracts paragraph and table content while maintaining heading hierarchy through the `level` attribute assigned to `Section` objects. This corresponds to Word's built-in heading styles (Heading 1, Heading 2, etc.), enabling the skill generator to understand document outline depth, though specific font styling and colors are stripped during extraction.

### Is the HTML parser capable of handling modern JavaScript-rendered single-page applications?

The HTML parser uses Python's standard `html.parser` module, which processes static markup only. It cannot execute JavaScript or render dynamic content injected by client-side frameworks. Users must provide server-side rendered HTML or pre-rendered snapshots for documents generated by React, Vue, or Angular applications.