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

> Discover the document formats book-to-skill supports for extraction including TXT, RTF, HTML, PDF, DOCX, EPUB, and more. Learn about its flexible backend strategy.

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

---

**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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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.

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/text.py), [`rtf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/rtf.py), [`html.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/html.py), [`pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/pdf.py), [`docx.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/docx.py), [`epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/epub.py), and [`calibre.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) for MIME type detection and [`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py) for command-line accessibility.