Math

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

(∑k=1nakbk)2≤(∑k=1nak2)(∑k=1nbk2)\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.

Delimiters around your formulae require the Passthrough configuration, as the theme finds your formulae by them. Passthrough syntax itself 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.

Parameters

Name Default Notes
align center The vertical alignment.

Allowed values are left, center or right.
<content> <empty> Your formulae.

Enclose each formula in the block or inline delimiters of your Passthrough configuration. Text outside of them is written as Markdown.

Without any delimiters, the whole content is one formula displayed as a block.

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.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]
  [params.math]
    output = 'htmlAndMathml'
params:
  math:
    output: htmlAndMathml
{
   "params": {
      "math": {
         "output": "htmlAndMathml"
      }
   }
}

Providing Options for KaTeX

Option Front Matter Besides output, you can set every option of Hugo’s transform.ToMath function in math, for example your own macros.

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

​
[math]
  [math.macros]
    '\R' = '\mathbb{R}'

[params]
math:
  macros:
    '\R': '\mathbb{R}'
params: {}
{
   "math": {
      "macros": {
         "\\R": "\\mathbb{R}"
      }
   },
   "params": {}
}

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=true. If a formula was rendered, the option has no effect.

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

​
[params]
  [params.math]
    force = true
params:
  math:
    force: true
{
   "params": {
      "math": {
         "force": true
      }
   }
}

Passthrough Configuration

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

hugo.
[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
{
   "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

In Passthrough default 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|$$"
)}}
∣abcd∣\left| \begin{array}{cc} a & b \\ c & d \end{array}\right|

Inline Math

In Passthrough default configuration, inline math is generated if you use a single $ as a delimiter around your formulae.

​
Euclid already knew, $\sqrt{2}$ is irrational.
Euclid already knew, {{< math >}}$\sqrt{2}${{< /math >}} is irrational.
Euclid already knew, {{ partial "shortcodes/math.html" (dict
  "page" .
  "content" "$\\sqrt{2}$"
)}} is irrational.
Euclid already knew, 2\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)$$"
)}}
(∑k=1nakbk)2≤(∑k=1nak2)(∑k=1nbk2)\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-}$$"
)}}
HgX2+→IX−HgIX2→IX−[HgXIIIX4]X2−\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}