sirdave73/epub2pdf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: USER_GUIDE updated for 18-format support (Phase 1)

Browse Source
This commit is contained in:
sirdave73
2026-09-02 03:03:43 -04:00
parent 345c39417b
commit 2931d547de
1 changed files with 37 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
USER_GUIDE.md
+37 -13
View File
@@ -1,7 +1,9 @@
# EPUB → PDF Converter — User Guide
# Document → PDF Converter — User Guide
A small, self-hosted web app that converts EPUB3 ebooks into typeset PDFs.
Everything runs locally (or on your own server); **no book ever leaves your machine**.
A small, self-hosted web app that converts common document formats —
EPUB3 ebooks, Markdown, HTML, plain text, CSV/TSV, JSON, XML, SVG,
images, and existing PDFs — into PDFs.
Everything runs locally (or on your own server); **no file ever leaves your machine**.
---
@@ -11,11 +13,29 @@ Everything runs locally (or on your own server); **no book ever leaves your mach
|---|---|
| Preserves the EPUB's own CSS, images, headings, tables, code blocks | Re-flow or re-typeset like a print publisher would |
| Renders CJK (Chinese / Japanese / Korean) correctly via Noto fonts | Handle DRM-protected (e.g. protected) EPUBs |
| Supports right-to-left books (Arabic, Hebrew) | Convert EPUB → other formats (only PDF out) |
| Keeps book title/author as PDF metadata | — |
| Supports right-to-left books (Arabic, Hebrew) | Convert *to* other formats (only PDF out) |
| Keeps book title/author as PDF metadata | Office formats (DOCX, PPTX, XLSX) — planned, not yet |
**Limits:** one book at a time per job (you can queue several, they render one after
another in the same server process), max upload size **400 MB**.
**Supported input formats (18):**
| Family | Extensions | Notes |
|---|---|---|
| Ebooks | `.epub` | Full CSS / images / metadata fidelity (the original mode) |
| Web | `.html` `.htm` | Native WeasyPrint rendering; `<script>` tags stripped |
| Markup | `.md` `.markdown` | Headers, tables, fenced code, links |
| Text | `.txt` `.log` | UTF-8 safe, paginated |
| Data | `.csv` `.tsv` | Auto-detected delimiter → styled table; max 5000 rows × 50 cols |
| Structured | `.json` `.xml` | Cleanly formatted listing |
| Vector | `.svg` | Embedded via WeasyPrint |
| Images | `.png` `.jpg` `.jpeg` `.webp` `.tiff` `.bmp` | One PDF page per image; max side 3000 px |
| PDF | `.pdf` | Pass-through with metadata re-stamping; max 500 pages; encrypted PDFs rejected |
Format is detected from the file's real bytes (magic), not the extension.
Naming: EPUBs use the book's title; everything else uses the file name (or the
document's H1 heading for Markdown/HTML), with `-2`, `-3` collision suffixes.
**Limits:** one file at a time per job (you can queue several, they render one after
another in the same server process), max upload **400 MB**, max output **200 MB**.
---
@@ -50,13 +70,14 @@ See `COOLIFY.md` in this directory (3 steps: Dockerfile service, port 8030, volu
## 3. Using the web UI
1. Open `http://<host>:8030` in your browser.
2. **Drop an `.epub` file** onto the upload box (or click to browse).
- Only `.epub` files are accepted; anything else is rejected with a message.
2. **Drop any supported file** onto the upload box (or click to browse).
- The 18 formats in §1 are accepted; anything else is rejected with a message.
- Files over 400 MB are rejected before upload finishes.
3. The job starts immediately — a progress bar shows which chapter is being
rendered (e.g. `Rendering chapter-04.xhtml (4/12)`), then `Merging pages…`.
3. The job starts immediately — progress updates show the current stage
(e.g. `Rendering chapter-04.xhtml (4/12)` for EPUBs), then `Done`.
4. When it finishes, a **Download PDF** button appears.
- The PDF is named after the book's title (e.g. `My_Book.pdf`).
- The PDF is named after the book's title (EPUBs) or the file name / H1 heading
(everything else), e.g. `My_Book.pdf`.
5. Repeat for the next book. Old jobs stay listed so you can re-download
recent PDFs (the server keeps the 50 most recent jobs and their outputs).
@@ -68,6 +89,9 @@ See `COOLIFY.md` in this directory (3 steps: Dockerfile service, port 8030, volu
| `No readable content found in EPUB spine` | The EPUB has no HTML chapters (images-only books, broken exports) |
| `DRM protected` style errors | Remove DRM first (Calibre / Calibre-DB tools) — this app can't decrypt |
| Stuck at `Working…` forever | The server restarted mid-job; refresh the page and re-upload |
| `Unsupported format` | File isn't one of the 18 supported types — see §1 |
| CSV/TSV rejected | Over 5000 rows or 50 columns — split the file |
| PDF rejected | Encrypted/password-protected, or over 500 pages |
---
@@ -108,7 +132,7 @@ curl -OJ http://localhost:8030/download/Book_Title-20260828-203943.pdf
Other endpoints:
- `GET /` — the web UI
- `GET /health` — `{"status":"ok","max_upload_mb":400}` (use for healthchecks)
- `GET /health` — `{"status":"ok","max_upload_mb":400,"supported_formats":[...]}` (use for healthchecks)
---