Math & Diagrams

Beautiful Hugo includes built-in support for KaTeX, MathJax, and Mermaid (diagrams and flowcharts). Mermaid needs no configuration. For math, enable the Goldmark passthrough extension (see below).

Math Rendering

Choose the math rendering engine via mathEngine in your config. See Configuration — Math Engine for the full option reference and selfHosted behavior.

Passthrough

Markdown removes backslashes and other characters from LaTeX before the browser sees it. The Goldmark passthrough extension keeps the math unchanged. Hugo does not merge the [markup] section of a theme configuration, so put this in your site configuration:

[markup.goldmark.extensions.passthrough]
  enable = true
  [markup.goldmark.extensions.passthrough.delimiters]
    block = [['\[', '\]'], ['$$', '$$']]
    inline = [['\(', '\)']]

Single $ is not an inline delimiter, because prose often contains a stray $. Add ['$', '$'] to inline if you want it.

With passthrough enabled, the theme loads the KaTeX or MathJax files only on the pages that contain math. Set math: true in the front matter of a page to load them anyway, for example if a shortcode or a partial adds the math. Without passthrough, the theme loads them on every page, and you must escape the delimiters (\\( in place of \().

Server-side rendering

Set mathRender = "server" to render KaTeX at build time, as this site does. Pages then load only the KaTeX CSS, and the math is visible before any script runs. See Configuration — Server-side rendering for the limits.

Inline math

The golden ratio is $\varphi = \frac{1+\sqrt{5}}{2} \approx 1.618$ . Euler’s identity states that $e^{i\pi} + 1 = 0$ .

Display math

\varphi = \frac{1+\sqrt{5}}{2}

\hat{f}(\xi) = \int_{-\infty}^{\infty} f(x)\, e^{-2\pi i x \xi}\, dx

\mathbf{A} = \begin{pmatrix} a_{11} & a_{12} \\ a_{21} & a_{22} \end{pmatrix}, \quad \det(\mathbf{A}) = a_{11}a_{22} - a_{12}a_{21}

\prod_{i=1}^n x_i = \exp\left(\sum_{i=1}^n \ln x_i\right)

Long equation test (mobile scroll behavior)

This very long equation tests horizontal scrolling on mobile devices:

f(x) = \sum_{n=0}^{\infty} \frac{f^{(n)}(a)}{n!}(x-a)^n = f(a) + f'(a)(x-a) + \frac{f''(a)}{2!}(x-a)^2 + \frac{f^{(3)}(a)}{3!}(x-a)^3 + \cdots = \int_a^x \int_a^{t_1} \int_a^{t_2} \cdots \int_a^{t_n} f^{(n+1)}(t_{n+1}) \, dt_{n+1} \, dt_n \cdots \, dt_2 \, dt_1 + \text{remainder terms}

Source

The golden ratio is \(\varphi = \frac{1+\sqrt{5}}{2}\).

$$
\varphi = \frac{1+\sqrt{5}}{2}
$$

KaTeX is loaded from CDN, or served from the site when selfHosted = true. MathJax is loaded from CDN even when selfHosted = true.

Mermaid

Mermaid renders diagrams from a simple text syntax. Write the diagram in a fenced code block with the mermaid language. A codeblock render hook turns it into a diagram. This is the recommended form. The mermaid shortcode is still supported and gives the same result.

Flowchart

graph TD
    A[User visits site] --> B{Has session?}
    B -->|Yes| C[Load preferences]
    B -->|No| D[Show defaults]
    C --> E[Render page]
    D --> E
    E --> F{Theme preference?}
    F -->|Light| G[Light theme]
    F -->|Dark| H[Dark theme]
    F -->|Auto| I[System preference]
    G --> J[Display content]
    H --> J
    I --> J

Sequence Diagram

sequenceDiagram
    participant U as User
    participant B as Browser
    participant S as Server
    participant DB as Database
    U->>B: Navigate to page
    B->>S: GET /api/data
    S->>DB: SELECT * FROM posts
    DB-->>S: Result set
    S-->>B: JSON response
    B->>B: Render content
    B-->>U: Display page

Gantt Chart

This one uses the shortcode:


gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    section Setup
        Configure Hugo      :done, setup1, 2026-01-01, 3d
        Install theme       :done, setup2, after setup1, 2d
    section Content
        Write pages         :active, content1, after setup2, 7d
        Add images          :content2, after content1, 3d
    section Deploy
        Build and test      :deploy1, after content2, 2d
        Go live             :milestone, deploy2, after deploy1, 0d

Source — Fenced Code Block

```mermaid
graph TD
    A[User visits site] --> B{Has session?}
    B -->|Yes| C[Load preferences]
    B -->|No| D[Show defaults]
    C --> E[Render page]
    D --> E
```

Source — Shortcode

{{< mermaid >}}
sequenceDiagram
    participant U as User
    participant B as Browser
    U->>B: Navigate to page
    B-->>U: Display page
{{< /mermaid >}}

Alignment

Set the horizontal alignment with a block attribute on the fence, or with the align parameter of the shortcode:

```mermaid {align="center"}
graph LR
    A --> B
```

center — centered (recommended for most diagrams)
left — left-aligned
right — right-aligned

Block attributes need markup.goldmark.parser.attribute.block = true in the site configuration.

Dark Mode

Mermaid diagrams are dual-rendered for light and dark themes. The theme uses .theme-light and .theme-dark CSS classes internally, so the correct version displays automatically based on the user’s color scheme preference. No extra configuration is needed.