convertmd2epub

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

Prerequisites

• Python 3.12 or later
• pip (included with Python)

On macOS, check your Python version:

python3 --version

If Python is not installed or too old, install it via python.org or Homebrew:

brew install python@3.12

Installation

With pip (recommended)

pip install .

With pipx (isolated install)

pipx install .

Development mode

pip install -e ".[dev]"

Quickstart

1. Create your Markdown chapters

mkdir my-book && cd my-book

Create a few .md files:

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

convertmd2epub init

This scans the directory for .md files and generates a book.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

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]

convertmd2epub build [FILES...] [--config PATH] [--format FORMAT] [--title T] [--author A] [--language L] [--verbose]

Direct file mode (no book.toml)

convertmd2epub build chapter1.md chapter2.md --title "My Book" --author "Jane"
convertmd2epub build ./my-chapters/
convertmd2epub build docs/*.md --format pdf

Multi-format output

convertmd2epub build --format epub    # default
convertmd2epub build --format mobi    # requires Calibre ebook-convert
convertmd2epub build --format pdf     # requires: pip install convertmd2epub[pdf]

Configuration Reference

[book] — Book metadata

[book.chapters] — Chapter list

[options] — Build options

Minimal example

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

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

Full example

[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:

python3 -m convertmd2epub --help

Or add the scripts directory to your PATH:

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:

pip install .

Wrong Python version

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

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