prosedown

Write books in Markdown. Compile to EPUB.

Like Fountain is for screenplays, ProseDown is for ebooks: plain text that compiles to a complex format. Two required fields, no custom syntax, no lock-in.

pip install prosedown View on GitHub → Read the Spec

v0.6.1 — initial public release · MIT licensed · on PyPI

Why this exists

Most ebook tools fall into one of three buckets — and each forces a tradeoff most authors don't want to make.

Closed editors
Vellum, Scrivener		Power tools
Pandoc, LaTeX		Raw editors
Sigil, Calibre		ProseDown
Plain text source—✓—✓
Open in any editor—✓—✓
EPUB output✓✓✓✓
Zero config✓——✓
Standard Markdownn/amostlyn/a✓
Free + MIT$250✓✓✓
EPUB → source—partial—✓ best-effort

ProseDown sits between: plain Markdown source files an author can open in any editor — Obsidian, VS Code, iA Writer, TextEdit — that compile to a professional EPUB by convention, with no configuration.

Five design principles

The decisions that shape every part of the format.

  1. One file is enough. A single .md with two YAML lines is a valid project. The barrier to entry is zero.
  2. Convention over configuration. Cover auto-detected. CSS auto-detected. Chapter order from filenames. Authors shouldn't configure what can be inferred.
  3. Standard everything. CommonMark Markdown. Standard YAML. No custom syntax. Lock-in is the enemy of adoption — and your files should outlive any single tool.
  4. Two directions. Build is primary, deterministic, EPUBCheck-clean. Deconstruct is best-effort and practical, not a lossless archive.
  5. Non-destructive. Opens cleanly in Obsidian, Hugo, Jekyll, or any other Markdown tool. A format that fights your other tools isn't a format worth adopting.

The whole tool, in seven lines

No configuration files, no project initializer, no template wizard.

$ cat > on-simplicity.md <<'EOF'
---
title: "On Simplicity"
author: "Jane Smith"
---

# On Simplicity

The simplest things are often the most profound.
EOF

$ prosedown build on-simplicity.md on-simplicity.epub

That's a valid EPUB 3.3. Passes EPUBCheck. Opens in Apple Books, Kobo, Calibre, anything that reads ebooks. Two required frontmatter fields. One Markdown file. No configuration.

How build works

Markdown source on the left, EPUB 3.3 on the right, a small handful of well-defined steps in the middle.

       your project           prosedown build              EPUB 3.3
   ┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
   │ book.md          │     │ parse YAML       │     │ META-INF/        │
   │ 01-intro.md      │ ──▶ │ resolve files    │ ──▶ │   container.xml  │
   │ 02-chapter.md    │     │ render Markdown  │     │ OEBPS/           │
   │ cover.jpg        │     │ build OPF/NCX    │     │   chapters/      │
   │ style.css        │     │ pack ZIP         │     │   images/        │
   │                  │     │                  │     │   nav.xhtml      │
   │                  │     │                  │     │   content.opf    │
   │                  │     │                  │     │ mimetype         │
   └──────────────────┘     └──────────────────┘     └──────────────────┘

deterministic · EPUBCheck-clean · same source → same bytes

Everything is auto-detected: cover by filename, CSS by filename, chapter order by numeric prefix. Same source produces the same bytes — diff-clean under git, reproducible builds work.

How deconstruct works (the other direction)

An existing EPUB on the left, a clean Markdown project you'd actually want to edit on the right.

      existing.epub             deconstruct            Markdown project
   ┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
   │ .epub (zip)      │     │ read OPF         │     │ book.md          │
   │   XHTML          │ ──▶ │ classify roles   │ ──▶ │ 000-cover.md     │
   │   + assets       │     │ walk spine       │     │ 001-chapter.md   │
   │   + OPF          │     │ XHTML → Markdown │     │ 002-chapter.md   │
   │                  │     │ extract images   │     │ ...              │
   │                  │     │ extract css      │     │ images/          │
   │                  │     │                  │     │ css/             │
   │                  │     │                  │     │                  │
   └──────────────────┘     └──────────────────┘     └──────────────────┘

best-effort · documented normalization · readable Markdown out

Building is the primary use case — stable and deterministic. Deconstruction is best-effort with documented normalization. The goal is readable Markdown an author would want to edit, not a lossless archive of the original EPUB.

ProseDown at a glance

If you only read one page, read this one. The full spec is the source of truth; this is the cheat sheet.

Required frontmatter

---
title: "Your Book"
author: "You"
---

Two fields. That's the floor. Everything else is inferred or optional.

Optional frontmatter

language: en           # default: en
publisher: "…"
date: 2026-04-30
isbn: "978-…"
description: |
  Short blurb.
cover: "cover.jpg"
css: "style.css"

All optional. ProseDown synthesizes a deterministic UUID from title + author + language.

Single-file project

my-essay.md     # frontmatter + body

One file, one essay, one EPUB. The barrier is zero.

Multi-chapter project

my-book/
  book.md          # frontmatter only
  00-copyright.md
  01-chapter-1.md
  02-chapter-2.md
  cover.jpg        # auto-detected
  style.css        # auto-detected

Filename order = chapter order. Numbered prefixes (01-, 02-) keep them sorted.

Conventional slugs

These filenames are auto-classified by role:

  • copyright, dedication, acknowledgments, foreword → frontmatter
  • part-1, part-2 → part dividers
  • afterword, about-the-author, colophon → backmatter
  • Anything else → chapter

Title resolution

  1. Frontmatter title:
  2. First # heading in body
  3. Deslugified filename

Same logic on deconstruct. Round-trips preserve the title source.

Standard Markdown

CommonMark + GitHub-flavored extensions: tables, definition lists, fenced code, footnotes ([^1]). No custom dialect.

Excluded files

_09-deleted-scene.md
_draft.md

Filenames starting with _ are skipped at build time. Useful for parking drafts in the same folder.

What ProseDown is not for

  • Fixed-layout (picture books, comics)
  • Poetry with line-level semantics
  • Drama formatting
  • Academic citations
  • Media overlays / read-aloud
  • PDF output

These are scope boundaries, not future features.

Read the full spec →

Pick your path

Three ways into ProseDown depending on what you're trying to do.

2

I want to understand the format

You're evaluating ProseDown for a workflow, a tool you're building, or curiosity about how the design hangs together.

  1. The spec — single source of truth
  2. Why ProseDown — the design rationale
  3. XHTML mapping — for implementers
  4. Roadmap — where it's going