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.
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):
$ https://github.com/bboc/mdtools.git 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 https://fletcherpenney.net/multimarkdown/, 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