Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


mdtools is a set of commandline scripts for creating electronic publications (books and slide-decks) in various output formats from a single source of (multi-)markdown files.

Publications created in mdtools are simple to tranlsate into other languages, as most translation platforms can handle all the formats used (markdown, html and po-files).

The S3 Practical Guide is built with mdtools as Github page, pdf and ePub in several languages, and uses most of the advanced features mdtools provides: glossaries, summaries, tags, and auto-genarated indexes, see the project's Github repository.

You can find an introduction and documentation to mdtools in the example project, which is also the source of the Github page for this repository.

The simplest way for getting started with your own project is to copy the example project and play around with it.


A powerful set of tools for rendering Github pages, and ebooks (pdf, ePub, Kindle format) from the same set of (Multi-)Markdown files. This makes it s

The structure of the book is defined in a yaml file, so that it is very simple to move around sections, chapters or parts, and a tag system allows for including or excluding files in different formats, and several other nifty features.

Image Update

Update image references in MultiMarkdown files (while preserving Deckset formatting). This is helpful when maintaining a large set of illustrations used in a large number of markdown file, because it allows for changing the folder structure of the illustrations without having to worry about updating all the references.

Usage: see mdimg -h


Output diff between two Markdown files as Critic Markup

Usage: see mddiff -h


Warning: in version 2.0, mdslides is not working, support for slide decks will come back in a later version.

Build slide decks from repositories of Markdown files for use in Deckset, reveal.js and Wordpress. This helps with reuse of slides and evolution of large decks.


Starting with version 2.0, mdtools is developed and tested in Python 3 only (Python 3.9.1 currently).


It's a good idea to install mdtools in a virtual environment.

Clone the project (alternatively download and unzip the files):

$ mdtools

Install dependencies and set up the commandline scripts:

$ make init


Most output formats require additional software:

  • ePub: requires Pandoc
  • pdf: requires Multimarkdown, latexmk and texlive-xetex
  • a Jekyll webpage would require a local Jekyll installations for testing changes to templates and CSS. For Github-pages, a local installation is not required, but often helpful.


Python 3.9, Pandoc and Multimarkdown can be installed via a package manager, e.g. Homebrew or MacPorts.

The simplest way to obtain latexmk and *texlive-xetex8 is the MacTex-Distribution

Instructions for installing Jekyll are available in the Jekyll documentation.


Install the required dependencies via the package manager:

$ sudo apt install latexmk texlive-xetex fonts-open-sans pandoc multimarkdown

On Linux, it might be necessary to Multimarkdown from source from, one user reported that in October 2020 the version in the Ubuntu repository was too old andid not work with mdtool.

Jekyll requires ruby, the installation process is described on this page

$ sudo apt install ruby-full