Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Build e-books (EPUB or PDF) out of markdown files

Project Description


Please note that you need either Calibre or Pandoc (or both) to generate EPUB files, but you need Calibre (and its CLI tools) to check the EPUB conformity.


Once the non-python requirements are installed, you can install system-wide, or inside a virtualenv:

pip install -e ./


to start a new book, just create a new project with the following command:

md2ebook start

or, alternatively:

md2ebook start directory-name

When you’re done, you can move to this directory and use the build command:

md2ebook build

This will build a HTML and a EPUB version of your book, as defined in the book.json file.

Extra commands

You can check your EPUB integrity using the following:

md2ebook check


For more help on the md2ebook command, simply type:

md2ebook --help

and you’ll get extensive documentation about commands and their options.


You can designate a cover for your ebook using one of the three options:

  • Adding a --cover argument to the command line,
  • Adding a cover key to your configuration file,
  • Leaving a cover.(png|jpg|jpeg|svg) file at the root of your project, this one will be used as a cover.

If none of them leads to an existing file, the ugly default cover will be used.

Please note that the configuration option or the optional argument may be a URL (yes, something like

Configuration file

At the root of your book directory, you have a book.json file which contains your book configuration. This file is mandatory.

Here are its mandatory options, as a complete example:

    "files": ["", "", ""],
    "author": "Joe A. Nonymous",
    "title": "What a beautiful title",
    "fileroot": "what-a-beautiful-title",
    "generator": "calibre"
  • files is a list of markdown files that live in your book root directory. They’ll be processed in that specific order and compiled into a single ebook.
  • author is the name of the author of the book.
  • title is the title of the book, in its full glory.
  • fileroot this string will serve as a root for the different outputs. Following the example, you’ll produce what-a-beautiful-title.html and what-a-beautiful-title.epub in your book root directory.
  • generator is either “calibre” or “pandoc”. Pick the one you prefer (or the one that is available on your system).

Extra configuration

  • pdf: triggers the PDF generation when using build. Set it to true or false. If not set, the PDF won’t be generated. Use the --with-pdf option to override this settings.
  • cover: will set the path of your cover. this must lead to an existing file and if possible, an image (png, jpg, jpeg, or even SVG).
  • extensions: this list of strings defines the Markdown Extensions you can add to parse the Markdown files. Please refer to the Markdown extension to use the supported extensions.

Note about the Markdown extensions

Here’s a list about the available extensions:

  • Extra (“extra”)
    • Abbreviations: (“abbr”)
    • Attribute list: (“attr_list”)
    • Definition Lists: (“def_list”)
    • Fenced Code Blocks: (“fenced_code”)
    • Footnotes: (“footnotes”)
    • Tables: (“tables”)
    • Smart Strong: (“smart_strong”)
  • Admonition: (“admonition”)
  • CodeHilite: (“codehilite”)
  • HeaderId: (“headerid”)
  • Meta-Data: (“meta”)
  • New Line to Break: (“nl2br”)
  • Sane Lists: (“sane_lists”)
  • Table of Contents: (“toc”)
  • WikiLinks: (“wikilinks”)

Here’s an example of config.json using the extensions:

"files": [
"title": "Les 3 Mousquetaires",
"fileroot": "les-3-mousquetaires",
"author": "Alexandre Dumas",
"extensions": ["admonitions", "toc", "footnotes"],
"generator": "pandoc"

Extension parameters are set as described in the docs

"extensions": ["headerid(level=3)"]


This piece of software is Copyleft 2013 - Bruno Bord.

It is released under the terms of the MIT License, see LICENSE file for more details.

Release History

Release History

This version
History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
md2ebook-0.1.1.tar.gz (8.7 kB) Copy SHA256 Checksum SHA256 Source Nov 23, 2013

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting