mkbooks

Turn Markdown chapters into a beautiful, paginated book you can read in the browser or export as PDF.

Features

• Markdown → Book — Write chapters in .md files, build a complete book with cover, TOC, and chapter navigation
• Interactive Reader — Swipe gestures, keyboard shortcuts, and tap zones for a native reading experience on any device
• PDF Export — Generate print-ready PDFs with proper page breaks, headers, footers, and margins (via Playwright + PagedJS)
• Light / Dark Themes — Switch reading modes instantly
• Single & Spread Layouts — One-page or two-page spread view, auto-detected based on screen size
• Reading Progress — Automatically saves and restores your chapter and page across sessions
• Auto-generated Cover — Styled cover from your title, subtitle, and author — or bring your own image
• Drop Caps — Optional decorative first letters on chapter openings
• Live Reload — mkbooks serve watches your files and rebuilds on every change
• Fully Configurable — Page size, margins, fonts, colors, and layout via mkbooks.yml

Installation

# With uv (recommended)
uv tool install mkbooks

# Local development
uv pip install -e .

Quick Start

# Create a new project
mkbooks new my-book

# Enter the project
cd my-book

# Add chapters
mkbooks add-chapter "Introduction"
mkbooks add-chapter "The Beginning"

# Build the book
mkbooks build

Commands

mkbooks new <name>

Creates a new project in a new folder.

mkbooks new my-book
mkbooks new my-book --title "My Great Book" --chapters 3

Options:

• -t, --title — Book title (default: project name)
• -n, --chapters — Number of initial chapters (default: 1)

mkbooks init

Creates a project in the current directory.

mkbooks init
mkbooks init --title "My Book" --chapters 2

Options:

• -d, --directory — Target directory (default: .)
• -t, --title — Book title
• -n, --chapters — Number of initial chapters

mkbooks add-chapter <title>

Adds a new chapter to the book.

mkbooks add-chapter "New Chapter"
mkbooks add-chapter "My Chapter" --file intro.md

Options:

• -c, --config — Configuration file
• -f, --file — Custom filename

mkbooks build

Generates the HTML book (and optionally PDF).

mkbooks build
mkbooks build --no-open
mkbooks build --pdf
mkbooks build --config another-book.yml

Options:

• -c, --config — Configuration file
• --no-open — Don't open browser automatically
• --pdf — Generate a PDF version (requires mkbooks[pdf], see below)

mkbooks serve

Builds and serves the book with live reload.

mkbooks serve
mkbooks serve --port 8000

Options:

• -c, --config — Configuration file
• -p, --port — Server port (default: 8765)

Configuration

The mkbooks.yml file defines the book structure and style:

book:
  title: "My Book"
  subtitle: "An incredible story"
  author: "Your Name"
  language: "en"
  year: "2026"
  
  # Cover (optional - if no image, an automatic cover is generated)
  cover:
    image: "cover.jpg"          # Optional
    title_color: "#ffffff"
    background_color: "#1a1a2e"
  
  # Chapters
  chapters:
    - file: chapter-1.md
      title: "Introduction"
    - file: chapter-2.md
      title: "The Beginning"
  
  # Styles
  style:
    page:
      size: "A5"
      margin_top: "20mm"
      margin_bottom: "25mm"
      margin_inner: "25mm"
      margin_outer: "20mm"
    font:
      body_family: "Georgia, 'Times New Roman', serif"
      body_size: "11pt"
      heading_family: "'Helvetica Neue', Arial, sans-serif"
      chapter_title_size: "28pt"
      line_height: "1.6"
    drop_cap: true
    chapter_break: "always"
  
  # Output
  output:
    directory: "output"
    filename: "book"
    open_browser: true

Cover

• With image: Set cover.image with the path to your image
• Without image: An automatic cover is generated with title, subtitle, and author

PDF Export

Generate a print-ready PDF directly from the command line:

mkbooks build --pdf

This requires the optional pdf extra and Chromium:

pip install mkbooks[pdf]
playwright install chromium

The PDF is rendered via headless Chromium using PagedJS, preserving all page layout, headers, footers, and margins from your configuration.

Reader Navigation

The built-in reader supports multiple input methods:

Method	Action
Swipe left / right	Next / previous page (touch devices)
Tap right side	Next page
Tap left side	Previous page
Tap center	Toggle toolbar
← → keys	Previous / next page
Home / End	Jump to start / end of book

Reading position is saved automatically and restored on next visit.

Requirements

• Python 3.12+
• (Optional) mkbooks[pdf] + Playwright for PDF generation

License

MIT