Choose the source of truth before converting
A source file is not automatically the authoritative record for every field. EPUB may contain reliable reading order and package metadata. A PDF may preserve the official page image. Markdown may be the publisher’s editable manuscript. A library catalog may contain identifiers and edition notes. Define which source controls title, contributors, dates, chapter order, rights, and canonical links before transforming content.
Format decision matrix
| Source | Strongest signals | Main risks | Good feed model |
|---|---|---|---|
| EPUB | Package metadata, manifest, spine, navigation, semantic XHTML | Package-only links, unsupported interactive content, rights assumptions | Edition alerts, authorized chapter serialization, OPDS acquisition |
| Page fidelity, outlines, tags, annotations, page labels | Broken reading order, columns, hidden OCR, fragile deep links | Document releases, chapter updates, archival page references | |
| HTML | Semantic headings, links, accessible structure, canonical web delivery | Scripts, dynamic content, changing DOM, copied boilerplate | Full-content feeds, excerpts, living guides |
| Markdown | Clean editorial text, headings, source control, easy diffs | Missing publication metadata, ambiguous asset paths, custom extensions | Serialized books, documentation-style publishing, release notes |
| Scans / photos | Visual evidence and page history | No searchable text, perspective, show-through, privacy, rights | Digitization milestones with page-image references |
| OCR text | Searchability and reflow | Recognition errors, lost layout, invented certainty | Reviewed chapters, searchable public-domain collections |
EPUB: respect the package graph
Read the package document, manifest, spine, and navigation. Do not sort filenames to infer chapter order. Keep contributor roles and multiple identifiers. If the feed contains chapter excerpts, sanitize XHTML conservatively, resolve authorized resources to absolute URLs, and include notes only when their references remain understandable. Use an enclosure only when the EPUB is intentionally distributed at a stable URL.
For the complete process, read EPUB to RSS: A Standards-Aware Publishing Workflow.
PDF: preserve logical units and page context
Inventory outlines, tags, page labels, annotations, and the reliability of the text layer. Use chapter- or document-level items unless page identity is central to the project. Canonical web pages should preserve page ranges, figures, tables, and facsimile links. Treat born-digital extraction and scanned-PDF OCR as separate pipelines.
The detailed PDF to Book RSS guide covers columns, notes, revisions, and stable page references.
HTML and Markdown: generate feeds with the pages
HTML and Markdown are excellent sources when the publisher controls them. Keep a structured front matter record for title, excerpt, date, modified date, canonical path, categories, tags, image, and rights. Generate pages and feed entries in the same build so URLs and metadata cannot drift. Strip scripts and navigation from full-content feed payloads.
OCR: publish review states, not raw confidence
Preserve the scan, preprocess representative pages, select language models, reconstruct layout, and store page-level provenance. Define review levels such as raw, automatically cleaned, structure-reviewed, text-reviewed, and proofread. Only records that meet the feed’s threshold should be published. Keep uncertain names, dates, and tables in a review queue.
See OCR Book Scans to RSS for the full review ladder and item design.
One normalized model, several outputs
{
"work_id": "work_8c2a",
"edition_id": "ed_2026_en_epub",
"title": "Harbor City Guide",
"contributors": [{"name": "Mira Chen", "role": "author"}],
"source_format": "application/epub+zip",
"rights": "owned",
"resources": [
{"type": "web", "url": "/books/harbor-city-guide/"},
{"type": "epub", "access": "download", "url": "/files/harbor-city-guide.epub"}
]
}Normalize only what the project can support accurately. Store provenance and source checksums. If a field is unknown, leave it unknown. The build should refuse to embed full text or distribute files when the rights status does not explicitly allow it.