Math

The math shortcode renders complex math and chemical formulae using Hugo’s built-in KaTeX.

\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)

Usage

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

```math {align="center"}
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
```

{{< math align="center" >}}
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
{{< /math >}}

{{ partial "shortcodes/math.html" (dict
  "page" .
  "align" "center"
  "content" "\\left( \\sum_{k=1}^n a_k b_k \\right)^2 \\leq \\left( \\sum_{k=1}^n a_k^2 \\right) \\left( \\sum_{k=1}^n b_k^2 \\right)"
)}}

You can also use pure Markdown for writing simple math expressions.

Passthrough syntax finds your formulae by their delimiters and requires the Passthrough configuration. It has limited features as it does not provide any of the below parameters besides content. Nevertheless, it is widely available in other Markdown parsers like GitHub and therefore is the recommended syntax for generating portable Markdown.

The codefence, shortcode and partial syntax take your formula without delimiters.

Parameters

Name	Default	Notes
align	`center`	The horizontal alignment. Allowed values are `left`, `center` or `right`.
<option>	<empty>	Any option of Hugo’s `transform.ToMath` function for this formula. It overwrites the option of the same name of your configuration. `displayMode` defaults to `true`, displaying the formula as a block. Set it to `false` to display the formula inline. With Passthrough syntax, it is decided by the delimiters around your formula. Not available for the codefence syntax, which always displays the formula as a block.
<content>	<empty>	Your formula without delimiters.

Settings

Output of the Formulae

Option Front Matter By default, formulae are written as MathML, which every current browser displays without any stylesheet or font of the theme. The display quality depends on the browser and the math fonts installed on your reader’s system.

If you want your formulae to look the same in every browser, set math.toMath.output to htmlAndMathml. The theme then links the KaTeX stylesheet and fonts to every page containing math. The MathML is kept for screen readers. The value html omits it.

params:
  math:
    toMath:
      output: htmlAndMathml

[params]
  [params.math]
    [params.math.toMath]
      output = 'htmlAndMathml'

{
   "params": {
      "math": {
         "toMath": {
            "output": "htmlAndMathml"
         }
      }
   }
}

Providing Options for KaTeX

Option Front Matter Besides output, you can set every option of Hugo’s transform.ToMath function in math.toMath, for example your own macros. displayMode is ignored here, as it is decided for each formula by its delimiters or the parameters of its call.

Each option of your page’s front matter overwrites the option of the same name of your configuration options.

Hugo lowercases the names of a map in your configuration and front matter, so a macro \Field would be known as \field. Give your macros as a list of name and definition pairs instead.

params:
  math:
    toMath:
      macros:
      - - '\Field'
        - '\mathbb{F}'

[params]
  [params.math]
    [params.math.toMath]
      macros = [['\Field', '\mathbb{F}']]

{
   "params": {
      "math": {
         "toMath": {
            "macros": [
               [
                  "\\Field",
                  "\\mathbb{F}"
               ]
            ]
         }
      }
   }
}

A formula that KaTeX can not render is written as its source and reported as a warning in your build.

Force Loading of the KaTeX Stylesheet

Option Front Matter If your output needs the KaTeX stylesheet, it will be linked to your page if the page contains a math shortcode, Markdown codefence, Passthrough syntax or the partial is called from your templates.

If you write KaTeX’s HTML by other means, you can force linking the stylesheet by setting math.force to true. If a formula was rendered, the option has no effect.

Setting math to true does the same but can’t be combined with other math.* options.

params:
  math:
    force: true

[params]
  [params.math]
    force = true

{
   "params": {
      "math": {
         "force": true
      }
   }
}

Passthrough Configuration

Passthrough syntax lets you write math without enclosing it in a shortcode or Markdown codefence. The theme finds your formulae by the delimiters of Hugo’s Passthrough configuration, so it is required for this syntax.

hugo.

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

See the example on how a Passthrough configurations makes using math really easy.

Examples

Block Math

With the above Passthrough configuration, block math is generated if you use two consecutive $$ as a delimiter around your formulae.

$$\left|
\begin{array}{cc}
a & b \\
c & d
\end{array}\right|$$

```math
\left|
\begin{array}{cc}
a & b \\
c & d
\end{array}\right|
```

{{< math >}}
\left|
\begin{array}{cc}
a & b \\
c & d
\end{array}\right|
{{< /math >}}

{{ partial "shortcodes/math.html" (dict
  "page" .
  "content" "\\left|\n\\begin{array}{cc}\na & b \\\\\nc & d\n\\end{array}\\right|"
)}}

\left| \begin{array}{cc} a & b \\ c & d \end{array}\right|

Inline Math

With the above Passthrough configuration, inline math is generated if you use a single $ as a delimiter around your formulae. With the shortcode and partial, set displayMode to false.

Euclid already knew, $\sqrt{2}$ is irrational.

Euclid already knew, {{< math displayMode="false" >}}\sqrt{2}{{< /math >}} is irrational.

Euclid already knew, {{ partial "shortcodes/math.html" (dict
  "page" .
  "content" "\\sqrt{2}"
  "displayMode" "false"
)}} is irrational.

Euclid already knew,

\sqrt{2}

is irrational.

Block Math with Right Alignment

With Passthrough syntax, only the content parameter is available.

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

```math {align="right"}
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
```

{{< math align="right" >}}
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
{{< /math >}}

{{ partial "shortcodes/math.html" (dict
  "page" .
  "align" "right"
  "content" "\\left( \\sum_{k=1}^n a_k b_k \\right)^2 \\leq \\left( \\sum_{k=1}^n a_k^2 \\right) \\left( \\sum_{k=1}^n b_k^2 \\right)"
)}}

\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)

Chemical Formulae

KaTeX can also render chemical formulae.

$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$

```math
\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}
```

{{< math >}}
\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}
{{< /math >}}

{{ partial "shortcodes/math.html" (dict
  "page" .
  "content" "\\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}"
)}}

\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}