What Document Formats Does book-to-skill Support for Extraction?

book-to-skill supports seven major document categories including plain text, RTF, HTML, PDF, Microsoft Word (DOCX), EPUB, and additional e-book formats via Calibre (AZW3, MOBI, FB2), using a cascading backend strategy that prefers pure-Python libraries and falls back to standard-library or external tools.

The book-to-skill library is designed to convert diverse document types into clean, skill-ready plain text. According to the source code in the virgiliojr94/book-to-skill repository, each format is handled by dedicated parsers located in the book_to_skill/parsers/ directory, which automatically select the best available extraction backend.

Supported Document Formats and Backends

The extraction architecture implements a priority-based fallback system. If the preferred third-party library is unavailable, the parser silently attempts the next backend until successful or exhausted.

Plain Text Files (.txt, .text)

Found in book_to_skill/parsers/text.py, the plain-text parser handles byte-order-mark (BOM) detection to automatically decode UTF-8, UTF-16, and UTF-32 encodings. If BOM detection fails, the system falls back sequentially through utf-8, cp1252, and latin-1 encodings via the read_text_file() function.

Rich Text Format (.rtf)

Located in book_to_skill/parsers/rtf.py, the RTF parser implements a two-tier strategy:

1. Primary: striprtf.striprtf.rtf_to_text (requires the striprtf package)
2. Fallback: Regex-based strip_rtf_fallback function for environments without external dependencies

HTML and HTM (.html, .htm)

The HTML extractor in book_to_skill/parsers/html.py provides robust web page text extraction:

1. Primary: BeautifulSoup (from the bs4 package) for structured parsing
2. Fallback: Minimal standard-library HTMLParser via the internal _HTMLTextExtractor class

PDF Documents (.pdf)

The PDF parser in book_to_skill/parsers/pdf.py offers the most extensive backend chain, ordered by extraction quality:

1. pdftotext (system binary): Cleans layout and de-hyphenates text
2. pypdf (pypdf.PdfReader): Pure-Python extraction
3. pdfminer.six (pdfminer.high_level.extract_text): Advanced layout analysis
4. docling: Optional layout-aware extraction for complex document structures

Microsoft Word (.docx)

Implemented in book_to_skill/parsers/docx.py, the Word parser prioritizes high-level APIs while maintaining safety:

1. Primary: python-docx for structured document traversal
2. Fallback: Standard-library zipfile combined with xml.etree.ElementTree for direct XML extraction, including XML safety validation

EPUB E-books (.epub)

The EPUB handler in book_to_skill/parsers/epub.py manages packaged HTML content:

1. Primary: ebooklib.epub combined with BeautifulSoup for XHTML parsing
2. Fallback: Standard-library zipfile parser that extracts HTML/XHTML files and processes them through the same minimal HTML extractor used for standalone HTML files

Additional E-book Formats via Calibre

For proprietary e-book formats, book_to_skill/parsers/calibre.py provides an optional integration with the Calibre library. This backend supports .azw3, .mobi, .fb2, and numerous other formats by using Calibre's archive handling, then extracting text through the HTML parser pipeline. This backend is only active when the Calibre Python library is installed.

Practical Extraction Examples

Each parser returns the extracted plain-text string (and often the backend name that succeeded). If a backend is unavailable, functions return None, allowing chained fallback logic.

from pathlib import Path
from book_to_skill.parsers.pdf import extract_with_pdftotext, extract_with_pypdf
from book_to_skill.parsers.docx import extract_docx
from book_to_skill.parsers.epub import extract_with_ebooklib
from book_to_skill.parsers.html import extract_html_file
from book_to_skill.parsers.rtf import extract_rtf
from book_to_skill.parsers.text import read_text_file

# -------- PDF ----------

pdf_path = Path("my_book.pdf")
text = extract_with_pdftotext(pdf_path) or extract_with_pypdf(pdf_path)
print(text[:200])          # show the first 200 characters

# -------- DOCX ----------

docx_path = Path("chapter.docx")
doc_text, backend = extract_docx(docx_path)
print(f"Extracted via {backend}:\n{doc_text[:150]}")

# -------- EPUB ----------

epub_path = Path("novel.epub")
epub_text = extract_with_ebooklib(epub_path) \
            or extract_with_zipfile(epub_path)   # fallback

print(epub_text.splitlines()[0])   # first line of the book

# -------- HTML ----------

html_path = Path("page.html")
html_text = extract_html_file(html_path)
print(html_text[:120])

# -------- RTF ----------

rtf_path = Path("notes.rtf")
rtf_text, backend = extract_rtf(rtf_path)
print(f"RTF extracted via {backend}:\n{rtf_text[:100]}")

Summary

• Seven format categories: Plain text, RTF, HTML, PDF, DOCX, EPUB, and Calibre-supported e-books (AZW3, MOBI, FB2)
• Cascading backends: Each parser tries premium libraries first (BeautifulSoup, python-docx, pypdf), then falls back to standard-library implementations
• Zero-dependency capable: Core functionality works without third-party packages, though optional libraries improve accuracy
• Source locations: All parsers reside in book_to_skill/parsers/ with specific files for text.py, rtf.py, html.py, pdf.py, docx.py, epub.py, and calibre.py
• Consistent interface: Functions return text strings and backend identifiers, with None signaling fallback requirements

Frequently Asked Questions

What happens if a required third-party library is not installed?

The library gracefully degrades to the next available backend. For example, if python-docx is missing, the DOCX parser automatically switches to the standard-library zipfile and xml.etree.ElementTree implementation. If all backends fail, the function returns None, allowing your application to handle the error or skip the file.

Which PDF extraction backend produces the best results?

According to the implementation in book_to_skill/parsers/pdf.py, the pdftotext system binary provides superior layout preservation and de-hyphenation compared to pure-Python alternatives. If pdftotext is unavailable, pypdf offers faster extraction while pdfminer.six provides more accurate layout analysis for complex documents. The optional docling backend delivers the best results for heavily formatted or column-based PDFs.

Does book-to-skill support password-protected documents?

The current implementations in the parser files do not specify password handling mechanisms. Standard decryption for PDFs or DOCX files would need to be handled externally before passing file paths to the extraction functions, as the extract_with_pdftotext, extract_docx, and related functions expect accessible file streams without encryption layers.

Can I extend book-to-skill to support additional formats like Markdown or AsciiDoc?

Yes. The modular architecture in book_to_skill/parsers/ allows extension by creating new parser modules following the established pattern: implement a primary extraction function that attempts a third-party library, followed by a fallback using standard libraries. Register your new format in book_to_skill/utils.py for MIME type detection and book_to_skill/cli.py for command-line accessibility.

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