For the documentation of JuPedSim we decided to go with a markdown-based approach, where every single article is written in markdown and published using Jekyll on GitHub-Pages. Very simple approach that allows focusing on writing the docs without any technical distraction.

However, somehow surprisingly, using the same markdown files to produce a printable pdf file for the documentation is not as straightforward as was expected.

A typical markdown file

A typical markdown file may have three objects that need to be rendered correctly in the pdf file:

Images with liquid syntax

![simulation]( { { site.baseurl } }/img/kobe.png)

$$ \alpha = \frac{\beta}{\gamma}. $$

Solution

In this article Peter J. Lu gives a nice summary what possibilities there are to convert markdown to pdf file and why there are a bunch of problems that you face when you do so.

The solution that he uses delivers the “best” possible result, but still requires some manual processing of the files.

Here is a script that helps fulfilling this “manual” cleaning in an automatic way. The steps to follow are:

Download the script that automates the above mentioned steps from here

The script creates a directory _tex and puts all the converted and cleaned tex files in it. The final step is to \input{} them in a master latex file to produce the finale pdf documentation.

Result

The above mentioned criteria are all given in this sample article.

And here is the resulting pdf file.

The JuPedSim guide is now available in PDF-format.

Tips

Things to keep in mind when writing the markdown files