DEV Community

zuka3
zuka3

Posted on

Dev.to KaTeX vs Standard LaTeX — What Works and What Doesn't

#latex #math #tutorial #katex

If you've used LaTeX before (in papers, Overleaf, or textbooks), you'll find that many things work differently — or don't work at all — on Dev.to. This is because Dev.to uses KaTeX, which covers a large subset of LaTeX but not everything.

This article is a reference for what's supported and what's not, with workarounds for common pain points.

The Key Difference: Liquid Tags

Standard LaTeX uses $...$ for inline math and $$...$$ for display math. Dev.to uses liquid tags:

Context Standard LaTeX Dev.to
Inline $x^2$ {% katex inline %} x^2 {% endkatex %}
Display $$x^2$$ {% katex %} x^2 {% endkatex %}

This is more verbose, but the rendering inside the tags follows standard KaTeX syntax.

What Works ✅

Environments

Environment Example Notes
aligned Multi-line aligned equations Use this instead of align
cases Piecewise functions
pmatrix, bmatrix, etc. Matrices All bracket types work
array Custom layouts
smallmatrix Inline matrices

Symbols and Commands

These all work as expected:

  • All Greek letters (\alpha through \omega, uppercase too)
  • Fractions: \frac, \dfrac, \cfrac
  • Roots: \sqrt, \sqrt[n]
  • Accents: \hat, \bar, \tilde, \vec, \dot
  • Operators: \sum, \prod, \int, \lim
  • Relations: \leq, \geq, \neq, \sim, \cong, \equiv
  • Logic: \forall, \exists, \neg, \land, \lor
  • Sets: \in, \subset, \cup, \cap, \emptyset
  • Arrows: \to, \Rightarrow, \iff, \mapsto
  • Fonts: \mathbb, \mathbf, \mathcal, \mathfrak, \mathrm, \text
  • Decorations: \color, \boxed, \cancel, \underbrace, \overbrace

What Doesn't Work ❌

1. align environment

This is the most common gotcha for LaTeX users.

Won't work:

{% katex %}
\begin{align}
a &= b + c \\
  &= d
\end{align}
{% endkatex %}
Enter fullscreen mode Exit fullscreen mode

Use instead:

{% katex %}
\begin{aligned}
a &= b + c \\
  &= d
\end{aligned}
{% endkatex %}
Enter fullscreen mode Exit fullscreen mode

The difference: align is a top-level environment in LaTeX (with auto-numbering). aligned is a sub-environment that works inside math mode, which is what KaTeX expects.

2. \newcommand (Custom Macros)

In LaTeX, you can define shortcuts:

% This doesn't work on Dev.to
\newcommand{\R}{\mathbb{R}}
\newcommand{\norm}[1]{\left\| #1 \right\|}
Enter fullscreen mode Exit fullscreen mode

Workaround: Write the full command every time. Use your editor's find-and-replace or snippets to save time while writing.

3. Auto-numbering and Cross-references 

% None of these work
\label{eq:main}
\ref{eq:main}
\eqref{eq:main}
Enter fullscreen mode Exit fullscreen mode

Workaround: Use \tag{} for manual numbering:

{% katex %}
E = mc^2 \tag{1}
{% endkatex %}
Enter fullscreen mode Exit fullscreen mode

E=mc2(1) E = mc^2 \tag{1}

You'll need to manage numbers by hand. If you add an equation in the middle, you'll need to renumber everything after it.

4. Theorem Environments 

% Not supported
\begin{theorem}
Every finite group of order p is cyclic.
\end{theorem}

\begin{proof}
...
\end{proof}
Enter fullscreen mode Exit fullscreen mode

Workaround: Use markdown formatting:

> **Theorem 1.** Every finite group of order p is cyclic.

<details>
<summary><b>Proof</b></summary>

... proof content ...

{% katex inline %} \square {% endkatex %}
</details>
Enter fullscreen mode Exit fullscreen mode

5. Diagrams (tikz, tikz-cd)

Commutative diagrams, graphs, automata — none of the tikz family works:

% Not supported
\begin{tikzcd}
A \arrow[r] & B
\end{tikzcd}
Enter fullscreen mode Exit fullscreen mode

Workaround: Generate diagrams externally and embed as images. Tools:

  • quiver for commutative diagrams
  • tikzjax for general tikz
  • Export to SVG/PNG and use ![diagram](url)

6. \DeclareMathOperator 

% Not supported
\DeclareMathOperator{\Hom}{Hom}
Enter fullscreen mode Exit fullscreen mode

Workaround: Use \operatorname{}:

{% katex %}
\operatorname{Hom}(A, B)
{% endkatex %}
Enter fullscreen mode Exit fullscreen mode
Hom⁡(A,B) \operatorname{Hom}(A, B)

Quick Reference: Substitutions

What you want Standard LaTeX Dev.to equivalent
Aligned equations \begin{align} \begin{aligned} inside katex block
Display equation $$...$$ {% katex %}...{% endkatex %}
Inline equation $...$ {% katex inline %}...{% endkatex %}
Custom macro \newcommand Write it out every time
Equation number \label + \ref \tag{1} manually
Named operator \DeclareMathOperator \operatorname{Name}
Theorem box \begin{theorem} Markdown blockquote + bold
Diagram tikz-cd External image

When KaTeX Isn't Enough

For most technical articles — algorithm analysis, ML math, basic proofs — KaTeX on Dev.to is sufficient. But if you're writing content that requires:

  • Commutative diagrams (algebra, category theory)
  • Formal theorem/proof environments with auto-numbering
  • Complex tikz drawings (graphs, automata)
  • Custom macros for long articles

You may want to consider a LaTeX-native platform. I've been using Folio for articles that need full LaTeX support — tikz-cd, theorem environments, \newcommand, all work out of the box.

Summary

  • Dev.to uses KaTeX via {% katex %} liquid tags — not $ syntax
  • Most standard math notation works fine
  • Main gaps: align (use aligned), no macros, no auto-numbering, no diagrams
  • For 90% of technical articles, these limitations don't matter
  • Know the workarounds, and you can write clean math on Dev.to

Top comments (0)