Bookfang

Convert user-supplied PDFs into readable, linked HTML instead of absolute-positioned page replicas.

Bookfang is a toolkit for converting books and other long-form PDFs into readable HTML where preserving reading order, heading hierarchy, page references, and special structures matters more than pixel-perfect fidelity.

Requirements

• Python 3
• PyMuPDF

Install the Python dependency with:

pip install pymupdf

Usage

Basic conversion:

python3 bookfang input.pdf output.html

Set a visible book title:

python3 bookfang input.pdf output.html \
  --title "Book Title"

Debug a page range:

python3 bookfang input.pdf output.html \
  --pages 15-56

Exclude printed page labels:

python3 bookfang input.pdf output.html \
  --exclude-printed-pages 326-333

Focus on a chapter by heading:

python3 bookfang input.pdf output.html \
  --start-at-heading '^Chapter 1\\b' \
  --stop-before-heading '^Chapter 2\\b'

Select a source-book mode:

python3 bookfang input.pdf output.html --source-book Generic

--source-book is case-insensitive. Supported values right now are Generic, WtF2e, and VtR2e. Generic is the default mode and skips the book-specific optimizations.

Code Layout

• bookfang is the thin CLI launcher.
• bookfanglib/core.py contains reusable extraction, ordering, rendering, and HTML/CSS helpers.
• bookfanglib/engine.py runs the generic conversion pipeline.
• bookfanglib/books/wtf2e.py contains the current Werewolf: The Forsaken 2e profile and its book-specific rules.

What It Tries to Preserve

• reflowable reading order
• heading hierarchy
• printed page anchors and references
• inline bold and italic markup when exposed by the PDF text layer
• epigraphs, fiction insets, sidebars, tables, and other non-body structures

Limits

This is a heuristic converter. Results depend heavily on the source PDF.

It works best on text-based PDFs with a usable text layer. Scanned PDFs, decorative layouts, complex tables, heavy sidebars, and image-only headings may still need OCR or manual tuning.

Legal Notes

This repository contains software only. It does not include third-party source PDFs or copyrighted book content.

Owning a PDF or book copy is not the same as owning the copyright to that work. Using this tool may implicate copyright law depending on the source material and what you do with the output.

All copyrights and trademarks in input documents remain with their respective owners. You are responsible for ensuring that you have the right to convert, store, share, or publish any source or generated document.

This project is not affiliated with or endorsed by any publisher or rights holder.

License

This project is licensed under the MIT License. See LICENSE.