Quick notes about writing LaTeX on dev.to

Embedding LaTeX mathematics in dev.to posts requires specific Liquid template tags. I didn’t find the tag syntax to be intuitive, hence this post is a set of notes intended to remind me. I also mention some of the downsides of using the dev.to solution for writing mathematics.

Image credits: dev.to, Wikimedia Commons

I repost almost all my articles from my blog to dev.to. Some of my articles are fairly maths-heavy and hence use a lot of LaTeX. The dev.to solution to embedding LaTeX-based mathematics into posts uses specific Liquid template tags and the KaTeX engine. In contrast, my blog uses MathJax, which I find does a good job of rendering the mathematics I wish to write. According to the KaTeX website, KaTeX is much faster than MathJax, and perhaps this is why the dev.to people decided to use it for their platform.

Writing KaTeX on dev.to

To create mathematical expressions and equations on dev.to, one uses the katex Liquid template tag. For instance, to render “displayed mathematics” (also known as “displaymath”), which displays mathematics separately from the main text, one would use code like this:

{% katex %}
i \hbar \frac{d}{dt} \left| \Psi \right> = \hat{H} \left| \Psi \right>
{% endkatex %}

which renders as:

\[i \hbar \frac{d}{dt} \left| \Psi \right> = \hat{H} \left| \Psi \right>\]

If one needs this to be a numbered equation, then the code to use is:

{% katex %}
\begin{equation}
i \hbar \frac{d}{dt} \left| \Psi \right> = \hat{H} \left| \Psi \right>
\end{equation}
{% endkatex %}

giving this output:

\begin{equation} i \hbar \frac{d}{dt} \left| \Psi \right> = \hat{H} \left| \Psi \right> \end{equation}

If the mathematics expressions or variables need to be part of the running text, add the inline attribute to the opening Liquid template tag, e.g.:

Where {% katex inline %}\hat{H}{% endkatex %} is the
Hamiltonian and {% katex inline %}\left| \Psi \right>{% endkatex %}
is the wave function.

which renders as:

Where \(\hat{H}\) is the Hamiltonian and \(\left| \Psi \right>\) is the wave function.

MathJax is more “naturally” LaTeX

Let’s compare the syntax to how one would write this in MathJax. To create displayed maths output, one can wrap the LaTeX code in $$ or between \[ and \]. This is very similar to what one would use when writing LaTeX on its own, and hence, it is much more natural for someone experienced with LaTeX.

Purists will point out that $$...$$ is actually TeX and not LaTeX; the syntax \[...\] is correct for displaymath in LaTeX. Either way, MathJax will render it as displayed mathematics.

Note that in Markdown, one has to escape the backslashes in \[...\] so that the actual code for displayed maths is \\[...\\], thus making it more enticing to simply use $$...$$ for all displayed maths equations.

I usually prefer to wrap my maths in an appropriate environment, thus I’m more inclined to write something like this for displayed maths:

\begin{equation}
a^2 + b^2 = c^2
\end{equation}

The nice thing about MathJax is that such code will render without the need to wrap it in anything, i.e. the above code renders as

\begin{equation} a^2 + b^2 = c^2 \end{equation}

and that’s written directly in Markdown! Cool!

The main difference between MathJax and standard LaTeX is that inline mathematics isn’t wrapped in single dollar signs ($...$); one needs to wrap the maths within \( and \).

Hence, the inline maths example from the previous section becomes:

Where \(\hat{H}\) is the Hamiltonian and \(\left| \Psi \right>\) is the
wave function.

where one must escape the backslashes in the \( and \) commands with backslashes so that Markdown doesn’t eat them. I.e. one has to write \\(...\\). Note that one can use $$...$$ for inline maths with MathJax in Markdown as well, but that’ll likely be frowned upon.

The problems with dev.to’s KaTeX

When using the dev.to KaTeX solution, I’ve run into some problems.

Verbosity

The Liquid tags for the KaTeX environment are lots of text, and it gets annoying having to write so much text to typeset mathematics. Consider, for example, when one wants to refer to a variable x within the running text (a very common task!). Here’s the code needed on dev.to:

{% katex inline %}x{% endkatex %}

That’s 33 characters just to display x correctly!

Consider the equivalent MathJax code:

\\(x\\)

which is seven characters when writing this in Markdown. If we’re prepared to “cheat”, then we can get this down to five characters:

$$x$$

Why does the dev.to solution have to be so verbose? I don’t know, but I find this to be a large stumbling block for me when reposting an article on dev.to.

Unhelpful error messages

If you get things wrong with the tags, often you’ll only be presented with an error message like this:

Liquid syntax error: 'katex' tag was never closed

That’s the only text you’ll see on the page! There won’t be any other text from your article to give some context about where the error occurred.

Mate! At least tell me where the problem is so that I can fix it!

I’ve been able to surmount such issues in the past, but if the post is long, the task can be daunting.

I’ve even gotten this error before:

ParseError: KaTeX parse error: Too many math in a row: expected 2, but got
6.5

which fortunately didn’t cause the entire text to disappear, and thus I was able to work out roughly where the problem in the Markdown was. Even so, what’s going on here? It seems that this problem was due to too many lines in a multi-line equation. I do wonder how much “6.5 math” is. Shouldn’t that be an integer?

No multi-line equation support

The amsmath environments are awesome. I’ve been using them since the late 90’s. Particularly useful, I find, are the align and alignat environments. These allow me to lay out a set of related equations nicely and align related parts of the equations with one another. KaTeX supports amsmath environments, including align and alignat. Unfortunately, dev.to doesn’t; at least, not really. Sure, the equations get rendered, but they all appear on one line, which definitely isn’t what I intended.

For instance, this set of equations from a recent article

\begin{align}
    V_c &= V_f - V_g\\
    &= \frac{5}{2} \pi h^2 + 4 \pi h
       - \biggl(\frac{5}{2} \pi h^2 - 4 \pi h + \frac{8}{5} \pi\biggr)\\
    &= \frac{5}{2} \pi h^2 + 4 \pi h
       - \frac{5}{2} \pi h^2 + 4 \pi h - \frac{8}{5} \pi\\
    &= 8 \pi h - \frac{8}{5} \pi.
\end{align}

gets rendered as:

To see everything, one has to scroll to the right, hence why one can’t see all the equations in the above image.

The correct rendering looks like this:

where I used the KaTeX demo page to create the image.

Admittedly, in MathJax, it’s necessary to wrap the LaTeX code in $$ to get the correct multi-line behaviour:

$$
\begin{align}
    V_c &= V_f - V_g\\
    &= \frac{5}{2} \pi h^2 + 4 \pi h
       - \biggl(\frac{5}{2} \pi h^2 - 4 \pi h + \frac{8}{5} \pi\biggr)\\
    &= \frac{5}{2} \pi h^2 + 4 \pi h
       - \frac{5}{2} \pi h^2 + 4 \pi h - \frac{8}{5} \pi\\
    &= 8 \pi h - \frac{8}{5} \pi.
\end{align}
$$

I’m not sure why that is because other environments, such as equation and equation*, work as-is without the need for wrapping. Oh well.

The only solution I’ve found to fix the multi-line-equations-on-one-line-problem on dev.to is to split lines of an align up into equation environments like this:

{% katex %}
\begin{equation}
first line
\end{equation}
{% endkatex %}

{% katex %}
\begin{equation}
second line
\end{equation}
{% endkatex %}

For several lines of a multi-line equation, it’s a lot of work wrapping each line in {% katex %} / {% endkatex %} blocks. Also, the rendered output doesn’t look as good anymore because things are no longer aligned.

Wrapping up

So, to create displayed mathematics on dev.to, wrap the LaTeX code like so:

{% katex %}
... displayed maths ...
{% endkatex %}

To create inline mathematics, use the inline attribute to the katex Liquid tag:

{% katex inline %} ... inline maths ... {% endkatex %}

But be warned, to create aligned multi-line equations, you will have to split each line into a separate equation. And if you screw something up, the error messages aren’t likely to be very helpful.

Support

If you liked this post and want to see more, please buy me a coffee!