Mathematical expressions are essential for technical documentation, academic papers, and scientific content. While standard Markdown doesn’t natively support math rendering, you can display beautiful mathematical formulas using LaTeX syntax combined with rendering engines like MathJax or KaTeX. This comprehensive guide covers everything you need to know about incorporating math expressions into your Markdown documents.

Why Use Math Expressions in Markdown?

Mathematical notation in Markdown offers several advantages:

  • Professional Appearance: Render complex equations with proper formatting
  • Universal Syntax: LaTeX is the standard for mathematical typesetting
  • Version Control Friendly: Text-based formulas work well with Git
  • Cross-Platform Compatibility: Works across different documentation platforms
  • Accessibility: Screen readers can process mathematical content when properly structured

LaTeX Math Syntax Basics

LaTeX provides a rich syntax for mathematical expressions. Here are the fundamental concepts:

Inline vs Block Math

Inline math appears within text using single dollar signs:

The formula $E = mc^2$ represents mass-energy equivalence.

Block math is displayed on separate lines using double dollar signs:

$$
E = mc^2
$$

Common Mathematical Elements

Fractions

$$
\frac{a}{b} = \frac{numerator}{denominator}
$$

Exponents and Subscripts

$$
x^2 + y^2 = z^2
$$

$$
H_2O + CO_2
$$

Greek Letters

$$
\alpha, \beta, \gamma, \delta, \epsilon, \pi, \sigma, \omega
$$

Square Roots

$$
\sqrt{x} + \sqrt[3]{y}
$$

Platform-Specific Implementation

GitHub and GitLab

GitHub recently added native support for math expressions:

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$.

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

GitHub uses MathJax for rendering, which supports most LaTeX math commands.

Jekyll and GitHub Pages

For Jekyll sites, you can enable math support by adding MathJax to your layout:

<!-- Add to _layouts/default.html or post.html -->
<script type="text/javascript" async
  src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.2/es5/tex-mml-chtml.js">
</script>

<script type="text/javascript">
  window.MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      displayMath: [['$$', '$$'], ['\\[', '\\]']]
    }
  };
</script>

If you’d rather avoid a client-side JavaScript library entirely, the jekyll-katex plugin renders LaTeX to static HTML at build time instead — no runtime script tag, no flash-of-unrendered-math on page load. Add it to your _config.yml:

plugins:
  - jekyll-katex

kramdown:
  math_engine: katex

The tradeoff: build-time rendering means every formula gets baked into the HTML during jekyll build, so there’s no per-page JavaScript cost, but you also can’t render math from JavaScript-injected content (e.g. content loaded after the page renders).

Hugo Static Site Generator

Hugo supports math rendering with KaTeX by default:

# In config.yml
markup:
  goldmark:
    renderer:
      unsafe: true
  highlight:
    style: github
    lineNos: true

params:
  math: true

Notion

Notion supports LaTeX math using the /math command or by typing $$:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Advanced Mathematical Expressions

Matrices and Vectors

$$
A = \begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
$$

A determinant uses the same row/column layout, just with \vmatrix instead of \pmatrix:

$$
\det(A) = \begin{vmatrix}
a & b \\
c & d
\end{vmatrix} = ad - bc
$$

Vectors are typically written with an arrow (\vec{}) or bold (\mathbf{}):

$$
\vec{v} = \langle v_1, v_2, v_3 \rangle = v_1\hat{i} + v_2\hat{j} + v_3\hat{k}
$$

Systems of Equations

$$
\begin{cases}
x + y = 5 \\
2x - y = 1
\end{cases}
$$

Integrals and Derivatives

$$
\frac{d}{dx}\int_a^x f(t)dt = f(x)
$$

$$
\int_0^{\pi} \sin(x) dx = 2
$$

Summations and Products

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

$$
\prod_{i=1}^{n} i = n!
$$

Limits

$$
\lim_{x \to \infty} \frac{1}{x} = 0
$$

Chemistry and Physics Notation

Chemical Formulas

$$
\ce{H2SO4 + 2NaOH -> Na2SO4 + 2H2O}
$$

Physics Equations

$$
F = ma = \frac{dp}{dt}
$$

$$
\nabla \cdot \vec{E} = \frac{\rho}{\epsilon_0}
$$

Statistics and Probability Notation

If your documentation covers data science or experiment results, these come up constantly:

$$
f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2}
$$

The normal distribution above, alongside Bayes’ theorem, are probably the two most commonly embedded formulas in technical blog posts and papers:

$$
P(A|B) = \frac{P(B|A) \cdot P(A)}{P(B)}
$$

Sample statistics tend to use overline/bar notation for means and subscripted sums:

$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n} x_i \qquad s^2 = \frac{1}{n-1}\sum_{i=1}^{n}(x_i - \bar{x})^2
$$

Computer Science and Algorithm Notation

Since this is a developer-focused site, it’s worth calling out the notation you’ll actually use when documenting algorithms rather than academic papers.

Big O notation is just inline math — no special syntax needed beyond the usual dollar-sign delimiters:

- Constant: $O(1)$
- Logarithmic: $O(\log n)$
- Linear: $O(n)$
- Linearithmic: $O(n \log n)$
- Quadratic: $O(n^2)$
- Exponential: $O(2^n)$

Recurrence relations (for documenting recursive algorithm complexity) use the cases environment, the same one shown in the systems-of-equations example above:

$$
T(n) = \begin{cases}
2T(n/2) + O(n) & \text{if } n > 1 \\
O(1) & \text{if } n = 1
\end{cases}
$$

Troubleshooting Common Issues

Escaping Special Characters

Problem: Underscores and other special characters breaking math rendering

Solution: Use backslashes to escape characters:

$$
\text{variable\_name} = x\_1 + x\_2
$$

Line Breaks in Equations

Problem: Long equations extending beyond page width

Solution: Use alignment environments:

$$
\begin{align}
f(x) &= ax^2 + bx + c \\
     &= a(x^2 + \frac{b}{a}x) + c \\
     &= a(x + \frac{b}{2a})^2 - \frac{b^2}{4a} + c
\end{align}
$$

Platform Compatibility

Problem: Math renders differently across platforms

Solution: Test your expressions on target platforms and use widely supported LaTeX commands:

<!-- Use standard commands for better compatibility -->
\sum, \int, \frac, \sqrt, \sin, \cos, \log

Best Practices

Readability Guidelines

  1. Use Descriptive Text: Explain complex equations in surrounding text
  2. Consistent Notation: Maintain consistent variable naming throughout documents
  3. Proper Spacing: Use \, for thin spaces and \quad for wider spaces
  4. Clear Structure: Break complex expressions into multiple steps

Performance Considerations

<!-- Preload MathJax for better performance -->
<link rel="preload" href="https://polyfill.io/v3/polyfill.min.js?features=es6" as="script">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js" as="script">

Accessibility

<!-- Use \text{} for descriptive text within formulas -->
$$
P(\text{success}) = \frac{\text{favorable outcomes}}{\text{total outcomes}}
$$

Rendering Engines Comparison

MathJax

Pros:

  • Excellent LaTeX compatibility
  • High-quality rendering
  • Wide platform support

Cons:

  • Larger file size
  • Slower initial load

KaTeX

Pros:

  • Faster rendering
  • Smaller bundle size
  • Server-side rendering support

Cons:

  • Limited LaTeX command support
  • Fewer advanced features

Implementation Example

<!-- MathJax -->
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

<!-- KaTeX -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js"></script>

Real-World Examples

Statistical Formulas

$$
\sigma = \sqrt{\frac{\sum_{i=1}^{n}(x_i - \mu)^2}{n}}
$$

Machine Learning

$$
J(\theta) = \frac{1}{2m}\sum_{i=1}^{m}(h_\theta(x^{(i)}) - y^{(i)})^2
$$

Calculus

$$
\frac{d}{dx}[f(g(x))] = f'(g(x)) \cdot g'(x)
$$

Worked Example: A Multi-Step Derivation

For documentation that walks readers through a proof or derivation rather than just stating a result, break it into steps with a $$ block per step. Here’s the quadratic formula derived by completing the square:

Starting with the general quadratic equation:
$$ax^2 + bx + c = 0$$

**Step 1:** Divide by the leading coefficient $a$:
$$x^2 + \frac{b}{a}x + \frac{c}{a} = 0$$

**Step 2:** Complete the square:
$$\left(x + \frac{b}{2a}\right)^2 = \frac{b^2 - 4ac}{4a^2}$$

**Step 3:** Take the square root and solve for $x$:
$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$

This pattern — bold step labels followed by a display-math block — reads well on GitHub, GitLab, and any KaTeX/MathJax-rendered site, and is far easier to follow than cramming the whole derivation into one block.

Testing and Validation

Always test your mathematical expressions across different platforms:

  1. Local Development: Preview in your local markdown renderer
  2. Target Platform: Test on GitHub, GitLab, or your documentation site
  3. Mobile Devices: Ensure formulas display correctly on smaller screens
  4. Browser Compatibility: Check rendering across different browsers

Integration with Other Markdown Features

Math expressions work well with other Markdown elements. You can create comprehensive technical documentation by combining mathematical formulas with tables in Markdown for data presentation, and use collapsible sections to organize complex mathematical proofs or derivations.

Tools and Further Reading

If you’d rather check a formula renders correctly than paste it blind, our Markdown Math Preview tool renders LaTeX live in your browser as you type, using KaTeX, with clear error messages if something doesn’t parse. And if you’re working across multiple platforms, see our guide to math rendering support across GitHub, GitLab, Obsidian, Notion, Jekyll, Hugo, Confluence, and Slack for exactly which ones render math natively versus needing a plugin or app.

Conclusion

Mathematical expressions in Markdown bridge the gap between simple text formatting and professional scientific documentation. By leveraging LaTeX syntax with rendering engines like MathJax or KaTeX, you can create beautiful, accessible mathematical content that integrates seamlessly with your documentation workflow.

Whether you’re writing academic papers, technical documentation, or educational materials, the combination of Markdown’s simplicity with LaTeX’s mathematical power provides an excellent foundation for communicating complex ideas clearly and effectively.

Remember to choose the right rendering engine for your needs, test across platforms, and follow accessibility best practices to ensure your mathematical content reaches the widest possible audience.