Maruku Make

A Makefile to render a maruku file in a variety of outputs

The problem

I love Markdown. I love that it can be rendered as a professional looking document, while still remaining human readable in its native form.

One shortcoming of Markdown is its inability to render mathematical formulas. You have a couple of options to solve this problem:

Write MathML inside your Markdown document.

This is the most simple solution, since Markdown gets parsed as HTML, and MathML is HTML. Markdown won't parse any HTML blocks in the document, so you can mix Markdown and HTML. It would have been my preffered solution if it did not break the one thing I love about Markdown human readability. To write human readable mathematical formulas there is only one real solution: Latex. That brings me to my second solution:

Use a Javascript library inside your Markdown.

I experimented with MathJax. MathJax allows you to enter mathematical formulas in Latex format and with Javascript converts it to MathML. Again, since Markdown gets parsed to HTML you can add the javascript library to your header section.

<head>
<script type='text/javascript' src='http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'></script>
</head>

and enter your formulas using Latex formatting

\[\begin{aligned}
\y = \sigma(y-x)\\
\z = x^y
\end{aligned} \]

Aside from having to escape a few characters this pretty readable.

Use Maruku

This is my preffered solution and the reason for this project. Maruku is a Ruby implementation of the Markdown parser with some extra features, including the ability to render mathemactical formulas written in Latex notation.

Dependencies

Maruku is implemented in Ruby, and you will need a recent version Ruby and RubyGems installed

To install Maruku using RubyGems run:

gem install maruku

To render the Mathematical formulas you need a math engine. I used Blahtex

Note: I installed blahtexml, a sequal to blahtex. To make this work with maruku I had to create a symlink of the blahtexml command to blahtex

ln -s /usr/bin/blahtexml /usr/bin/blahtex

Usage

Copy the Makefile into the directory with your Markdown file. If the markdown file is myfile.md, you have the following targets available:

make myfile.pdf

make myfile.tex

make myfile.html

These targets will put the corresponding output files in the output directory.

make clean_tmp

Removes the directory containing the temporary files used to create the output files.

make clean_output

Removes the directory containing the output files

make clean

Does both clean_tmp ande clean_output

Shortcomings

Both the Javascript and Maruku solutions described above will only work for your personal documents. Online resources like Github will not render it.

tjaartvdwalt/maruku-make