transform.ToMath

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}" }}

{{ $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:

1. Let KaTeX throw an error and fail the build. This is the default behavior.
2. Set the throwOnError option to false to make KaTeX render the expression as an error instead of throwing an error. See options.
3. 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
            }
         }
      }
   }
}

Step 2 #

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

{{- $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.

<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.

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

These are block equations:

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

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