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)

• Code snippets

<crossing>
<vertex px="10.0" py="6.0"/>
</crossing>

• and embedded latex like $$\alpha$$ or equations like

$$\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:

• Convert the markdown file to latex with Kramdown.

kramdown _posts/file.md --no-auto-ids --output latex > file.tex

• Cleanup file.tex by removing the YAML headers:

for line in lines:
# look for first appearance of "---"
continue # ignore this line
newlines.append(line)

• Fix the image paths: replace liquid tags like site.baseurl by an absolute path.

line = re.sub(r"\{\{\s* site.baseurl \s*\}\}", os.getcwd(), line)


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 can be produced as a pdf file. See PDF-format.

Tips

Things to keep in mind when writing the markdown files

• Always specify the language of code snippets.
• use -syntax to write math-symbols.
• Use scaled images. Otherwise, you will have to do so manually in the latex files.