convertmd2epub 0.3.0

Convert Markdown files to EPUB

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]

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

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

Option	Description
FILES	Markdown files or directories (alternative to --config)
--config, -c	Path to book.toml (default: book.toml)
--format, -F	Output format: epub, mobi, pdf (default: epub)
--title, -t	Book title (overrides config)
--author, -a	Book author (overrides config)
--language, -l	Language code ISO 639-1 (overrides config)
--verbose, -v	Show detailed output and validation result
--epubcheck	Run W3C epubcheck validation (requires Java)

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

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

[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