ProseDown recovers a reflowable EPUB into a folder of Markdown chapters and local image assets. Use it when you want to revise an old manuscript, search book text, or bring editable chapters into a Markdown workflow. Recovery is best-effort; keep the original EPUB.
Extract a book into a Markdown project
With Python 3.10 or later, install the released command-line tool:
python -m pip install prosedown
prosedown deconstruct original.epub recovered/
Use a new output folder. The 0.7 draft additionally rejects nonempty output
folders and publishes recovered projects only after extraction succeeds. Draft
changes require installation from a checkout containing those changes using
python -m pip install -e ..
What files do you get?
The result is a ProseDown project. Exact chapter names depend on the source book:
recovered/
book.md
00-introduction.md
01-first-chapter.md
02-second-chapter.md
images/
css/
book.md holds book metadata. Chapter files follow the EPUB’s reading order.
Referenced images are recovered as local files, and source CSS is extracted
when present. An image-free book will not have an images folder.
Review what changed (0.7 draft)
A successful recovery also writes .prosedown/recovery.txt and
.prosedown/recovery.json. Read the text report for losses, items requiring
review, and expected normalization. It identifies source archive paths for
removed link targets, complex tables, unsupported content, unrecovered
resources, and CSS dependencies. JSON findings have stable codes and occurrence
counts for scripts.
An empty report does not prove lossless recovery. Reports describe each source EPUB and are not included when rebuilding. Fatal errors do not publish a partial project or report. With the draft installed, validate recovered sources using:
prosedown check recovered/
What survives the conversion?
| Content | Recovery behavior |
|---|---|
| Title, authors, language | Recovered from EPUB metadata when available |
| Chapter order | Follows the EPUB spine, its declared reading sequence |
| Headings and paragraphs | Converted to Markdown |
| Emphasis, lists, quotations, code | Converted to editable source; complex structures may normalize |
| Images | Extracted and linked as local assets |
| Heading links | The 0.7 draft maps source heading IDs to recovered heading slugs |
| Local semantic footnotes | Converted to Markdown note definitions; external note documents need review |
| Custom CSS and fonts | CSS can be extracted, but resource URLs and embedded fonts are not fully recovered |
The current draft tests nested code, rich definitions, and structured local footnotes through repeated rebuilds. That coverage does not imply lossless conversion of every third-party EPUB.
Open EPUB chapters in Obsidian or another editor
Recovered files are ordinary .md documents. Open the folder in your editor,
or copy its chapters and image folder together into your notes workspace.
Keeping the assets beside the chapters preserves relative image references.
ProseDown uses standard Markdown links. It does not resolve Obsidian-specific
wikilinks or ![[image]] embeds when rebuilding, so convert those to normal
Markdown syntax first. Editor support for extended syntax can differ.
Edit the Markdown and rebuild the EPUB
After editing, compile the recovered folder:
prosedown build recovered/ revised.epub
Review the chapter order, follow internal links, inspect images, and check the
notes. Validate revised.epub with
EPUBCheck before sharing it. The
Markdown to EPUB guide explains book structure and styling.
Why does the rebuilt book look different?
Recovery normalizes XHTML into readable source. Decorative spans, custom layout,
complex tables, and arbitrary anchor targets may not survive. Extracted CSS can
refer to resources that need manual repair. If you prefer ProseDown’s default
style, remove the css: setting from recovered metadata and move the recovered
css/style.css out of the project so it is not auto-detected.
See the EPUB typography sample before choosing a style.
Can it convert protected books, PDFs, or scans?
No. ProseDown does not remove DRM, perform OCR, or import PDF. The current importer rejects EPUBs containing encryption metadata, including some books with obfuscated fonts. Start with a compatible, unencrypted EPUB.
Does the book leave my computer?
The conversion commands operate locally. There is no ProseDown upload service, account requirement, or hosted conversion step. Installing Python packages may require an internet connection; the conversion itself works on local files.