Metadata-Version: 2.4
Name: mkbooks
Version: 0.1.0
Summary: Turn Markdown chapters into a beautiful, paginated book you can read in the browser or export as PDF
Author-email: blasferna <blasferna@gmail.com>
Requires-Python: >=3.12
Requires-Dist: click>=8.1
Requires-Dist: jinja2>=3.1
Requires-Dist: markdown>=3.5
Requires-Dist: pygments>=2.17
Requires-Dist: pyyaml>=6.0
Requires-Dist: watchdog>=4.0
Provides-Extra: pdf
Requires-Dist: playwright>=1.40; extra == 'pdf'
Description-Content-Type: text/markdown

# 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

```bash
# With uv (recommended)
uv tool install mkbooks

# Local development
uv pip install -e .
```

## Quick Start

```bash
# 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.

```bash
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.

```bash
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.

```bash
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).

```bash
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.

```bash
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:

```yaml
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:

```bash
mkbooks build --pdf
```

This requires the optional `pdf` extra and Chromium:

```bash
pip install mkbooks[pdf]
playwright install chromium
```

The PDF is rendered via headless Chromium using [PagedJS](https://github.com/pagedjs/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
