Math Formulas in Markdown

Image by Elchinator from Pixabay

In this article, I’d like to share my setup for writing notes in Markdown with mathematical formulas using LaTeX syntax. I use vim and neuron for that. I mostly work on Mac, but the setup for my Linux laptop doesn’t differ significantly.

neuron for notes

neuron implements a note-taking approach called Zettelkasten. There’s a lot to be said about this great tool (including that it’s soon going to be superseded by even cooler Emanote). But for this article, I’m only focusing on its ability to generate neat HTML pages with mathematical formulas based on Markdown and LaTeX syntax.

First, I install the Nix package manager using this guide for macOS. As soon as it’s ready, I enable Nix cache for neuron and install neuron itself according to the docs:

nix-env -iA cachix -f https://cachix.org/api/v1/install
cachix use srid
nix-env -if https://github.com/srid/neuron/archive/master.tar.gz

I then create a folder for my notes and put an empty neuron.dhall file there:

mkdir ~/zettelkasten
touch ~/zettelkasten/neuron.dhall

At this point, I should be able to run neuron static page generator with autoreload on port 31337 (nothing specific, I just like the number):

cd ~/zettelkasten
neuron gen -ws :31337

I now see the following at http://localhost:31337:

vim for editing

I use vim for editing my notes, but you can use pretty much any text editor. For vim, it’s best to install markdown support using the vim-markdown plugin. Here’s how I do it.

First, I set up vim-pathogen to simplify subsequent installation of vim plugins:

mkdir -p ~/.vim/autoload ~/.vim/bundle
curl -LSso ~/.vim/autoload/pathogen.vim https://tpo.pe/pathogen.vim

Next, I add the following lines to my ~/.vimrc configuration file, to initialize vim-pathogen:

execute pathogen#infect()

You might want to add the following lines to .vimrc to ensure proper highlighting and indentation. I also like to have line numbers in my files, so I add set number:

syntax on
filetype plugin indent on
let g:vim_markdown_math = 1
set number

Next, I clone the vim-markdown repository in the .vim/bundle folder:

cd ~/.vim/bundle
clone git@github.com:plasticboy/vim-markdown.git

At this point, I’m able to write Markdown in vim with syntax highlighting both for regular Markdown syntax and mathematical formulas. One-shot formulas are written inside $...$ and multiline formulas are demarcated by a double-dollar sign:

$$
...
$$

Here’s this snippet in a copy-and-pasteable form:

# Header
## Header 2
* hello 1
* hello 2
```
println("Hello world!')
```
$E=mc^2$
$$
\begin{equation}
a =
\begin{cases}
1, & b = true \\
2, & b = false \\
\end{cases}
\end{equation}
$$

If I now go to http://localhost:31337/README.html, I see that this code was transformed to a neatly formatted page with mathematical formulas:

That’s it! Writing math formulas in Markdown is super-easy.