mdfusion

A Python module for merging and exporting Markdown files. Available for pip.

#Python

When I am studying for exams, I often end up with a lot of Markdown files in a folder hierarchy. For revising the content, I want to merge these files into one single file and have them in a nicely readable format.

When looking for a solution, I did not find a tool that would crawl the directory for me, merge the files and export them to a PDF or HTML file in one go. So I wrote a small Python module that does exactly that. Since I feel like this is a common use case, I decided to publish it on GitHub and PyPI.

The code is available on GitHuband on PyPI.

Project Setup

Even though this is a small project, I manage it in a git repository using

  • pytest for unit tests
  • pythons build module and twine for uploading the package to PyPI
  • black for code formatting when a file is saved in VSCode

Documentation

mdfusion

Merge all Markdown files in a directory tree into a single PDF with beautiful formatting via Pandoc + XeLaTeX.

Features

  • Recursive Markdown merge: Collects and sorts all .md files under a directory (natural sort order).
  • PDF output via Pandoc + XeLaTeX: Produces a polished PDF with centered section headings and small margins.
  • Title page and metadata: Optional title page with configurable title, author, and date.
  • Config file support: Use a .mdfusion INI-style config file for repeatable builds.
  • Custom LaTeX header: Inject your own LaTeX via header.tex if desired.
  • Image link rewriting: Converts relative image links to absolute paths, so identically-named images in different folders don't collide.

Installation

Install via pip

pip install mdfusion

Install from source

  1. Clone this repo
  2. Install Python 3.8+ and Pandoc with XeLaTeX support
  3. Install the mdfusion package:
pip install ./mdfusion

Usage

mdfusion ROOT_DIR [OPTIONS]

Common options

  • -o, --output FILE Output PDF filename (default: <root_dir>.pdf)
  • --no-toc Omit table of contents
  • --title-page Include a title page
  • --title TITLE Set title for title page (default: directory name)
  • --author AUTHOR Set author for title page (default: OS user)
  • --pandoc-args ARGS Extra Pandoc arguments (whitespace-separated)
  • -c, --config FILE Path to a .mdfusion INI-style config file

Example

mdfusion --title-page --title "My Book" --author "Jane Doe" docs/

Configuration file

You can create a .mdfusion file in your project directory:

[mdfusion]
root_dir = docs
output = my-book.pdf
no_toc = true
title_page = true
title = My Book
author = Jane Doe
pandoc_args = --number-sections

Then just run:

mdfusion

How it works

  • Finds and sorts all Markdown files under the root directory
  • Merges them into one file, rewriting image links to absolute paths
  • Optionally adds a YAML metadata block for title/author/date
  • Inserts page breaks between files
  • Calls Pandoc with XeLaTeX and a custom header for formatting

Testing

Run all tests with:

pytest

Author

ejuet

Comments

Feel free to leave your opinion or questions in the comment section below.