### Louis Moresi

Professor of Geophysics Australian National University Canberra, Australia +61 4 0333 1413

Email Twitter Facebook Google+ Github Youtube Researchgate

# Mathematics and Code

This post was originally written for the “logdown” platform but I recently ported the whole lot across to github and their jekyll-based environment. I have therefore generalised my comments and I am showing only what works on github too. [ Sept 4, 2015 ]

We’ve had a frantic phase of development in Underworld recently with a new python and ipython compatible version in the wings. Using the ipython notebook environment exclusively for a couple of weeks has rekindled my appreciation of (multi)markdown for documentation and the power of rendering mathematics with mathjax. I even gave a lecture this week using ipython to make slides (I wouldn’t actually recommend this, but it was interesting to be able do live demonstrations where I could modify my code to show off some numerical instabilities).

I wondered if there was a web-hosting or blogging site that had the markdown, mathematics, code-highlighting capabilities of ipython notebooks, and I found www.logdown.com. This is what it can do:

## Mathematics

Display equations rendered with mathjax as a raw displayed equation

  \$S \frac{\partial h}{\partial t} + H = -\frac{\partial }{\partial x} \underbrace{\left( - K \frac{\partial h}{\partial x} \right)}_\text{flux} \$


Producing: $S \frac{\partial h}{\partial t} + H = -\frac{\partial }{\partial x} \underbrace{\left( - K \frac{\partial h}{\partial x} \right)}_\text{flux}$

and you can use inline equations so that you can explain, for example, what $${\partial h}/{\partial t}$$ means by using \$$… \$$ tags.

Although mathjax will parse and (etc) markup successfully in some documents, it can be pretty hit and miss just how the different processing engines will battle it all out. Luckily, mathjax is highly configurable and you can usually find some combination of things that work. If you do use the latex begin / end tags, then it is possible to switch on equation numbering and labels. Who knows if this is really portable. Here is an example that works, I just had to be careful to escape the backslashes (i.e. \)

$$S \frac{\partial h}{\partial t} + H = -\frac{\partial }{\partial x} \underbrace{\left( - K \frac{\partial h}{\partial x} \right)}_\text{flux}$$

$$\nabla \cdot \phi = 0$$

## Code

Code highlighting is also platform dependent. Markdown does this in a variety of ways, with Github using fenced code blocks and logdown adopting their strategy. In Jekyll, I found it hard to have consistent code block detection and highlighting without using the liquid { % highlight language % } and { % endhighlight % } tags

Code highlighting works for $$\LaTeX$$,

python scripts:

and C code (C-like code … this is StGermain after all)

I highly recommend the logdown platform. If you are using github, though, it is not too much of a stretch to get things working directly with Jekyll and keep everything in one spot. We’ll see, I suppose !