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 `\begin{equation}`

and `\end{equation}`

(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. `\\begin{equation}`

)

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

\begin{equation} \nabla \cdot \phi = 0 \end{equation}

## 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 !