This post was written with the assistance of AI.

MathJax Support

This site renders mathematical notation in posts using MathJax. MathJax is a JavaScript display engine that typesets TeX and MathML directly in the browser, so no server-side rendering is required.

How it works

Support is enabled by two pieces working together.

Kramdown configuration

Kramdown is the Markdown converter that Jekyll uses to turn post sources into HTML. It extends standard Markdown with features such as tables, footnotes, and math blocks, and it can hand math off to a configurable engine.

In _config.yml the Markdown converter is told to use MathJax as its math engine:

kramdown:
  math_engine: mathjax

Kramdown recognizes $$...$$ in the Markdown source and converts it into the $...$ and \[...\] delimiters that MathJax expects. This happens at build time, so the math is left as-is in the generated HTML for the browser to render.

MathJax script

MathJax runs in the browser and receives the page as ordinary HTML, so it cannot tell on its own which characters are math. It therefore scans the page for matching pairs of delimiters and renders only the text between them. Without those delimiters MathJax would find nothing to typeset.

_includes/head.html is the shared <head> snippet: the opening block of an HTML page that holds site-wide setup not shown in the body, such as the stylesheet link and the MathJax loader. Each post’s front matter sets layout: default, and that layout inserts head.html at the top and the post’s rendered text in the page body. A post therefore supplies only the article content, while head.html wraps every post with the same page-level setup, which is why one edit here enables math everywhere.

This file loads MathJax from a CDN and configures its delimiters:

<script>
  window.MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      displayMath: [['$$', '$$'], ['\\[', '\\]']],
      processEscapes: true
    },
    options: {
      skipHtmlTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
    }
  };
</script>
<script id="MathJax-script" async
  src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

The tex settings declare $...$ and $...$ as inline delimiters and $$...$$ and \[...\] as display delimiters. The $...$ and \[...\] pairs are the important ones here: Kramdown rewrites $$...$$ into those forms before the page reaches the browser, so MathJax must recognize them to render the math. The $ and $$ pairs additionally cover any math that arrives unconverted.

The skipHtmlTags option keeps MathJax from touching code blocks, so math-like text inside pre and code elements is shown literally.

The page layout

Every page is assembled by a layout: a template that defines the overall page structure and marks where the page’s own content is inserted. This site uses the default layout, stored in _layouts/default.html:

<!DOCTYPE html>
<html lang="...">
  {%- include head.html -%}
  <body>
    {%- include header.html -%}
    <main class="page-content">
      <div class="wrapper">
        {%- include ai-declaration.html -%}
        {{ content }}
      </div>
    </main>
    {%- include footer.html -%}
  </body>
</html>

The layout has two similarly named parts that serve different purposes:

head (_includes/head.html) is the opening <head> block. It holds information about the page that is not displayed in the body: the title metadata, the stylesheet, the RSS feed link, and the MathJax loader. This is where the math support lives.
header (_includes/header.html) is the visible banner at the top of the body: the site title and the navigation links to the other pages. It is the part readers see above the content.

In short, head describes the page behind the scenes, while header is the part of the page readers actually see. {{ content }} marks where the post’s rendered Markdown goes, and the AI-assist notice is inserted just before it.

Usage

Wrap math in $$...$$ for both inline and display notation. Place it inside a sentence for inline math, or on its own paragraph for display math.

MathJax Example

This section demonstrates math typesetting with MathJax. Use $$...$$ for both inline and display math; Kramdown marks it up and MathJax renders it in the browser.

Inline math

The mass-energy equivalence is given by $E = mc^2$, where $c$ is the speed of light.

Einstein’s field equations can be written as $G_{\mu\nu} + \Lambda g_{\mu\nu} = \frac{8\pi G}{c^4} T_{\mu\nu}$.

Display math

The quadratic formula for $ax^2 + bx + c = 0$ is

\[x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}\]

A summation and an integral:

\[\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6} \qquad \int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}\]

A matrix:

\[\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} x \\ y \end{pmatrix} = \begin{pmatrix} ax + by \\ cx + dy \end{pmatrix}\]

Math inside a code block is left untouched:

$$ \text{this is shown literally} $$