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

Book-to-Skill processes EPUB, DOCX, and HTML files by delegating to dedicated parser modules—epub.py, docx.py, and 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, which inspects file extensions and dispatches to the appropriate parser. Every parser adheres to a unified interface contract:

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 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 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.

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, which utilizes the python-docx library. The implementation loads the .docx archive with Document, then walks through paragraphs and tables while preserving heading hierarchy.

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, 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.

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. 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, 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, 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 normalizes Unicode and removes control characters before skill generation.
• Extensible configuration in 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 and maps it to the corresponding parser module defined in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}