node package manager
Stop wasting time. Easily manage code sharing in your team. Create a free org »


Please Share on Twitter if you like #mdbook

%MarkDown to Book Readme % by Anthony McCormick


mdbook wraps the Pandoc and kindlegen CLI tools with a grunt task.

Any books that you can create using Pandoc you should be able to create using this task.

Please visit the pandoc documentation for full details



npm install mdbook --save

Other Dependencies


Pandoc is the only required CLI tool however if you want to create PDF or KINDLE(mobi) files then you need to install extra tools outlined below.


In order to build out PDF files you need to install MACTEX so that you can use PDFLATEX this is a rather huge download of more than 2.gig once downloaded unpack and run the following commands

find /usr/ -name "pdflatex"
ln -s /path/to/pdflatex /usr/local/bin


In order to build mobi files that can be used on kindle devices you need to download KINDLEGEN once downloaded unpack it and run the following command.

ln -s /path/to/kindlegen /usr/local/bin

You can now build all the available types mentioned in the Usage guide.



The Sample book ( the one your reading right now ) comes with a sample Gruntfile.js that shows how to create the following versions of your book.

  • MD

  • HTML

  • EPUB

  • RTF

  • PDF

  • KINDLE (mobi)

The Gruntfile pulls its data from the package.json file for details about the books metadata. For example the book title, Author and language.

Combining markdown files into one

The first step required in order to compile the book is combining of the individual markdown files into one. If you look at the example Gruntfile you will see a shell command that combines all the source markdown files into one markdown file with the title passed in the configuration file. You can run this combine task with the following command.

grunt shell:combine

Running the sample project

Change directories to the mdbook folder and then run grunt to create various versions of this book in HTML, EPUB, MOBI etc..

cd node_modules/mdbook/

or build only one type of book with one of the following commands.

grunt readme
grunt html
grunt epub
grunt rtf
grunt pdf
grunt kindle



mdbook supports all of pandocs options through it's own options object. However there is one required value that is not an option and that is the files property. This can be an array of files however it is best to combine all the markdown files into one file before passing it to this property as then it will create all the correct hyperlinks for you within your book. If you pass an array of markdown files then it will link to each markdown file and not the generated output.

pandoc :{
    files: compiledMarkdownFile


dest Location where you would like the book output. If the folder does not already exist it will be created. If are outputting html then you should consider using the --self-contained flag to force inclusion of your linked assets

-o : Output file name for example index.html or Title.pdf.

-c : CSS file to associate with the document for example html.css or epub.css

-s : All other pandoc options can be referenced through the command options for example you can set -t epub to make your book an epub book or you can set --toc to create a table of contents please refer to the options from the pandoc documentation.

kindle : If set to true then you must pass an epub file as the files parameter. This task will then output a kindle mobi file generated using kindlegen

Including scripts

MD2Book includes a haskell script that will allow you to link in your code rather than copy pasting it into the MD files. Anywhere from within your .md files you can add the following code which will place the included file into a code block with the style set to whatever style you wish to have applied.

~~~~ {include="tasks/mdbook.js" style="javascript"}


include : Path to the file to include.


style : Style of the code

This will produce for example:




Automatically load the include filter so that GruntFiles do not need to be updated.

See [Including scripts] for details.


Added the ability to include external files so that code can be linked to rather than copy pasted into the book.

See [Including scripts] for details.


Initial Release

Please Share on Twitter if you like #mdbook