transform.ToMath

Renders mathematical equations and expressions written in the LaTeX markup language.

Syntax

transform.ToMath INPUT [OPTIONS]

Returns

types.Result[template.HTML]

Hugo uses an embedded instance of the KaTeX display engine to render mathematical markup to HTML. You do not need to install the KaTeX display engine.

{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}

By default, Hugo renders mathematical markup to MathML, and does not require any CSS to display the result.

To optimize rendering quality and accessibility, use the htmlAndMathml output option as described below. This approach requires an external stylesheet.

{{ $opts := dict "output" "htmlAndMathml" }}
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" $opts }}

Options

Pass a map of options as the second argument to the transform.ToMath function. The options below are a subset of the KaTeX rendering options.

displayMode: (bool) If true render in display mode, else render in inline mode. Default is false.
errorColor: (string) The color of the error messages expressed as an RGB hexadecimal color. Default is #cc0000.

fleqn

(bool) If true render flush left with a 2em left margin. Default is false.

macros

(map) A map of macros to be used in the math expression. Default is {}.

{{ $macros := dict
  "\\addBar" "\\bar{#1}"
  "\\bold" "\\mathbf{#1}"
}}
{{ $opts := dict "macros" $macros }}
{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}

minRuleThickness

(float) The minimum thickness of the fraction lines in em. Default is 0.04.

output

(string). Determines the markup language of the output, one of html, mathml, or htmlAndMathml. Default is mathml.

With html and htmlAndMathml you must include the KaTeX style sheet within the head element of your base template.

<link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">

throwOnError

(bool) If true throw a ParseError when KaTeX encounters an unsupported command or invalid LaTeX. Default is true.

Error handling

There are three ways to handle errors:

Let KaTeX throw an error and fail the build. This is the default behavior.
Set the throwOnError option to false to make KaTeX render the expression as an error instead of throwing an error. See options.
Handle the error in your template.

The example below demonstrates error handing within a template.

Example

Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the transform.ToMath function.

Step 1

Enable and configure the Goldmark passthrough extension in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.

markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block:
          - - \[
            - \]
          - - $$
            - $$
          inline:
          - - \(
            - \)
        enable: true

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

{
   "markup": {
      "goldmark": {
         "extensions": {
            "passthrough": {
               "delimiters": {
                  "block": [
                     [
                        "\\[",
                        "\\]"
                     ],
                     [
                        "$$",
                        "$$"
                     ]
                  ],
                  "inline": [
                     [
                        "\\(",
                        "\\)"
                     ]
                  ]
               },
               "enable": true
            }
         }
      }
   }
}

The configuration above precludes the use of the $...$ delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you will need to double-escape the $ symbol when used outside of math contexts to avoid unintended formatting.

Step 2

Create a passthrough render hook to capture and render the LaTeX markup.

layouts/_default/_markup/render-passthrough.html

{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{- with try (transform.ToMath .Inner $opts) }}
  {{- with .Err }}
    {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
  {{- else }}
    {{- .Value }}
    {{- $.Page.Store.Set "hasMath" true }}
  {{- end }}
{{- end -}}

Step 3

In your base template, conditionally include the KaTeX CSS within the head element.

layouts/_default/baseof.html

<head>
  {{ $noop := .WordCount }}
  {{ if .Page.Store.Get "hasMath" }}
    <link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
  {{ end }}
</head>

In the above, note the use of a noop statement to force content rendering before we check the value of hasMath with the Store.Get method.

Step 4

Add some mathematical markup to your content, then test.

content/example.md

This is an inline \(a^*=x-b^*\) equation.

These are block equations:

\[a^*=x-b^*\]

$$a^*=x-b^*$$

Chemistry

New in v0.144.0

You can also use the transform.ToMath function to render chemical equations, leveraging the \ce and \pu functions from the mhchem package.

$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$

C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}

Last updated: February 14, 2025 : content: Updates for v0.144.0 (8e1e104aa)

Improve this page