md2book

A simple Python utility that turns Markdown collections into printable or digital books (PDF, EPUB, and MOBI). It can work with local Markdown files/directories or clone a GitHub repository (for example, a Docsify-powered documentation site) and export the result using configurable typography.

Features

• Accepts local Markdown files/directories or a GitHub repository URL.
• YAML-based theming for fonts, colors, margins, and page sizing.
• Automatic table of contents and optional page breaks per chapter.
• Generates PDF (via WeasyPrint), EPUB (via EbookLib), and MOBI (via pypandoc or Calibre's ebook-convert) outputs.
• Sensible defaults to minimize required configuration.

Installation

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

WeasyPrint may require system libraries such as Cairo, Pango, and gdk-pixbuf. Refer to the WeasyPrint installation guide if you need to add OS packages on your Linux distribution. MOBI output depends on either pypandoc (with the pandoc binary installed) or Calibre's ebook-convert command-line tool; install one of them alongside the Python requirements.

Usage

python md2book.py <sources>... [options]

• <sources>: One or more Markdown files, directories, or a GitHub repository URL (e.g., https://github.com/DistSysCorp/ddia). When a repository URL is supplied, it will be cloned into a temporary folder and all Markdown files will be processed.

Examples

Convert a couple of local Markdown files into a PDF:

python md2book.py intro.md chapter-*.md -o book

Clone a GitHub repository and export both PDF and EPUB with a custom config:

python md2book.py https://github.com/DistSysCorp/ddia -c my-config.yaml -o ddia --format both

Process a directory tree of documentation:

python md2book.py ./docs --format epub

Generate a Kindle-friendly MOBI alongside the EPUB:

python md2book.py ./docs --format mobi

Use an image file as the first-page PDF cover:

python md2book.py intro.md --pdf-cover ./cover.png

Configuration

Settings are read from a YAML file. If no file is supplied, defaults are used. See config.example.yaml for a full list of options. Key fields include:

• title, author, language (authors accept Markdown for inline links/emphasis)
• font_family, heading_font_family, chapter_title_font_family, base_font_size, line_height
• heading_color, heading_color_h1, heading_color_h2, heading_color_h3 (per-level heading colors; default #77AAC2)
• text_color, background_color, link_color
• table_cell_padding (default 6px 12px for th/td padding)
• page_size, margin_top, margin_bottom, margin_left, margin_right
• chapter_page_break (start each chapter on a new page)
• toc (include a generated table of contents)
• header_* / footer_* settings (toggle headers/footers, choose chapter titles, set font sizes, and dashed separators)
• url_prefix (base URL used to build links in running headers back to the online chapters)
• extra_css for last-mile styling tweaks
• metadata (arbitrary EPUB metadata entries)
• pdf_cover (path to an image that will be used as the first page of the PDF)
• epub_cover (path to an image for the EPUB cover)

Output

• book.pdf — PDF with CSS-driven styling (page size/margins applied via @page rules).
• book.epub — EPUB with embedded CSS and chapters split per Markdown source file.
• book.mobi — MOBI converted from the generated EPUB using pypandoc (with pandoc installed) or ebook-convert.

Notes

• Markdown conversion relies on the markdown package with extensions for fenced code, tables, code highlighting classes, anchors, and attribute lists.
• Local asset paths (images, etc.) will be resolved relative to the first source directory when generating the PDF. Keep assets alongside your Markdown files for portability.
• MOBI generation requires either the pandoc binary (for use with pypandoc) or Calibre's ebook-convert on your PATH.
• If you notice that chapter fonts aren’t rendering correctly, change the heading_font_family and chapter_title_font_family in the config to font families that exist on your machine and have complete coverage.