home / posts

Extension to Markdown Supporting LateX-Style Theorem Environments, References and Citations

Extended Markdown - New Commands

One of the motivations for developing an extension to Markdown was a desire to have a way to automatically and easily add theorems and proofs that are styled in a similar manner to LateX. Such 'environments' are not supported by MathJax, which only deals with math expressions. Furthermore, I thought it would be nice for the theorems etc. to be numbered automatically with an easy way to reference them throughout a post. To accommodate such new features, I chose a syntax to specify commands in a Markdown file. A command is signalled by an exclamation (!) mark followed by the alphanumeric name of the command. If the command takes arguments, each argument is enclosed in braces and follows immediately after the name of the command (this is in fact modelled after LateX). So to invoke the theorem command, take a look at the code below. The arguments of the theorem command are first, the label of the theorem (so that it can easily be referenced) and second, the content of the theorem. So we write:

!theorem{th:primes}{There are an infinite number of primes.}

It is rendered as

1. There are an infinite number of primes.

I call this extension to Markdown, rather lazily, ExtMarkdown, which is not very unique considering the many extensions to Markdown out there. Also we have commands for definitions, lemmas and proofs. Then there is a reference (!ref) command whose only argument is the label of the theorem, lemma or definition to be referenced. Here is some elementary mathematical content that serves to illustrate the commands.

1. A semigroup consists of a set together with a binary operation satisfying the following properties.
  1. The set is closed under the binary operation.
  2. The binary operation is associative.

Now we have the following theorem.

2. The set $S := \{x^2 + y^2 : x, y \in \mathbb{Z}^+\}$ together with the binary operation of integer multiplication is a semigroup.
Associativity follows immediately from that of integer multiplication. However, we must show that the set is closed under multiplication. This can be seen as follows $$(x_1^2 + y_1^2)\cdot(x_2^2 + y_2^2) = x_1^2x_2^2 + x_1^2y_2^2 + x_2^2 y_1^2 + y_1^2y_2^2 = x_1^2x_2^2 + x_1^2y_2^2 + x_2^2y_1^2 + y_1^2y_2^2 + 2x_1x_2y_1y_2 - 2x_1x_2y_1y_2 = (x_1x_2 + y_1y_2)^2 + (x_1y_2 - x_2y_1)^2$$. Therefore, $(S, \ast)$ is a semigroup as it satisfies the properties of Definition 1.

Note that we used a '!ref' command in the proof of Theorem 2 to reference Definition 1 (and twice in this very sentence). See the raw ExtMarkdown by following the link at the end of the post.

The CSS I use for the theorem etc. environments is from a post by Zach Harmony.


Another useful command that I've added is '!cite' for citation of papers etc. It takes one argument, namely a BibTeX key, which locates an entry in a BibTeX bibliography file that is specified in the uberlight configuration. A list of references is automatically generated and appended to the end of the post. Updates can cite articles that are cited in the main post, and if they make citations to articles not cited in the main post, a list of 'further' references is appended to the update. To illustrate citations, I will now arbitrarily cite [1].

Note as of writing, I have not as yet put the code on GitHub. I will do this very soon and add an update to this post to say that it has been made available.


  1. Scargos: Towards Automatic Vulnerability Distribution. Florian Rhinow and Michael Clear. SECRYPT. 2015.
Raw form (ExtMarkdown)


Update 1

The PHP code for the ExtMarkdown parser here consists of a quick-and-dirty implementation of a "parser"/interpreter that is suboptimal and not easy to read. However it suffices for my needs at the moment, but I would love to create a proper lexer/parser in PHP from a grammar that would give O(n) performance. I've taken a quick look at some options but don't have the time at the moment.

Update 2

The code for the ExtMarkdown parser (written in PHP) is available now on GitHub as part of the uberlight blog engine. See the repository here.