Metadata-Version: 2.4
Name: convertmd2epub
Version: 0.2.0
Summary: Convert Markdown files to EPUB
Project-URL: Homepage, https://github.com/thibmonier/convertmd2epub
Project-URL: Repository, https://github.com/thibmonier/convertmd2epub
Project-URL: Issues, https://github.com/thibmonier/convertmd2epub/issues
Project-URL: Changelog, https://github.com/thibmonier/convertmd2epub/blob/main/CHANGELOG.md
Author-email: Thibaut Monier <thibaut.monier@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: converter,ebook,epub,markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: ebooklib>=0.18
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: mdit-py-plugins>=0.4
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# convertmd2epub

Convert Markdown files to EPUB — a simple CLI for authors and technical writers.

![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
![License MIT](https://img.shields.io/badge/license-MIT-green)
[![CI](https://github.com/thibmonier/convertmd2epub/actions/workflows/ci.yml/badge.svg)](https://github.com/thibmonier/convertmd2epub/actions/workflows/ci.yml)

## Prerequisites

- **Python 3.12** or later
- **pip** (included with Python)

On macOS, check your Python version:

```bash
python3 --version
```

If Python is not installed or too old, install it via [python.org](https://www.python.org/downloads/) or Homebrew:

```bash
brew install python@3.12
```

## Installation

### With pip (recommended)

```bash
pip install .
```

### With pipx (isolated install)

```bash
pipx install .
```

### Development mode

```bash
pip install -e ".[dev]"
```

## Quickstart

### 1. Create your Markdown chapters

```bash
mkdir my-book && cd my-book
```

Create a few `.md` files:

```bash
cat > ch01-introduction.md << 'EOF'
# Introduction

Welcome to my book.
EOF

cat > ch02-getting-started.md << 'EOF'
# Getting Started

Let's begin.
EOF
```

### 2. Generate the configuration

```bash
convertmd2epub init
```

This scans the directory for `.md` files and generates a `book.toml`:

```toml
[book]
title = "Mon Livre"
author = "Author"
language = "fr"

[book.chapters]
files = [
    "ch01-introduction.md",
    "ch02-getting-started.md",
]
```

Edit `book.toml` to set your title, author, and language.

### 3. Build the EPUB

```bash
convertmd2epub build
```

Your EPUB is ready at `book.epub`. Open it with Apple Books, Calibre, or any EPUB reader.

## CLI Reference

```
convertmd2epub init [DIRECTORY] [--force]
```

| Option | Description |
|--------|-------------|
| `DIRECTORY` | Directory containing `.md` files (default: `.`) |
| `--force`, `-f` | Overwrite existing `book.toml` |

```
convertmd2epub build [--config PATH] [--verbose]
```

| Option | Description |
|--------|-------------|
| `--config`, `-c` | Path to `book.toml` (default: `book.toml`) |
| `--verbose`, `-v` | Show detailed output and validation result |

## Configuration Reference

### `[book]` — Book metadata

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `title` | string | yes | — | Book title |
| `author` | string | yes | — | Author name |
| `language` | string | no | `"en"` | Language code (BCP 47) |
| `subtitle` | string | no | — | Subtitle |
| `description` | string | no | — | Book description |
| `cover` | string | no | — | Path to cover image (JPEG or PNG) |
| `output` | string | no | `"book.epub"` | Output file path |

### `[book.chapters]` — Chapter list

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `files` | list of strings | yes | Ordered list of Markdown files |

### `[options]` — Build options

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `toc` | boolean | `true` | Generate table of contents |
| `toc_depth` | integer | `2` | Heading depth for TOC (1–6) |
| `css` | string | — | Path to custom CSS file |
| `no_default_css` | boolean | `false` | Disable built-in e-ink CSS |
| `validate_epub` | boolean | `true` | Validate EPUB structure after build |

### Minimal example

```toml
[book]
title = "My Book"
author = "Jane Doe"

[book.chapters]
files = ["chapter1.md", "chapter2.md"]
```

### Full example

```toml
[book]
title = "The Complete Guide"
author = "Jane Doe"
language = "en"
subtitle = "Everything you need to know"
description = "A comprehensive guide."
cover = "cover.jpg"
output = "dist/guide.epub"

[book.chapters]
files = [
    "00-preface.md",
    "01-introduction.md",
    "02-getting-started.md",
    "03-advanced-topics.md",
    "04-appendix.md",
]

[options]
toc = true
toc_depth = 3
css = "custom.css"
validate_epub = true
```

## Troubleshooting

### `command not found: convertmd2epub`

Your Python scripts directory may not be in your PATH. Try:

```bash
python3 -m convertmd2epub --help
```

Or add the scripts directory to your PATH:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Add this line to `~/.zshrc` to make it permanent.

### `No module named 'convertmd2epub'`

Make sure you installed the package:

```bash
pip install .
```

### Wrong Python version

If you have multiple Python versions, use `python3.12` explicitly:

```bash
python3.12 -m pip install .
```

## Supported Markdown Features

- Headings (H1–H6)
- Paragraphs, bold, italic, strikethrough
- Ordered and unordered lists
- Code blocks (fenced and indented)
- Links and images (local files)
- Tables
- Blockquotes
- Footnotes

## License

MIT
