+++
categories = ['howto', 'reference']
description = 'Beautiful math and chemical formulae'
frontmatter = ['customMathJaxURL', 'math', 'math.force', 'mathJaxInitialize']
options = ['customMathJaxURL', 'math', 'math.force', 'mathJaxInitialize']
title = 'Math'
+++

The `math` shortcode renders complex math and chemical formulae using the [MathJax](https://mathjax.org/) library.

{{% multishortcode name="math" print="false" %}}
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)$$
{{% /multishortcode %}}

## Usage

{{% multishortcode name="math" execute="false" %}}
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)$$
{{% /multishortcode %}}

You can also use [pure Markdown](authoring/markdown#subscript-and-superscript) for writing simple math expressions.

Passthrough syntax is only available by [further configuration](#passthrough-configuration) and 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.<br><br>Allowed values are `left`, `center` or `right`. |
| _**&lt;content&gt;**_ | _&lt;empty&gt;_  | Your formulae. |

## Settings

### Providing Initialization Options for the MathJax Library

{{% badge style="option" %}}Option{{% /badge %}} {{% badge style="frontmatter" %}}Front Matter{{% /badge %}} The MathJax library is configured with default settings for initialization.

You can overwrite the settings by providing a JSON object in `mathJaxInitialize`. See [MathJax's documentation](https://docs.mathjax.org/en/latest/options/index.html) for all allowed settings.

Keep in mind that initialization settings of your pages front matter overwrite all settings of your configuration options.

{{< multiconfig section=params >}}
mathJaxInitialize = '{ "chtml": { "displayAlign": "left" }, { "tex": { "inlineMath": [["\(", "\)"], ["@", "@"]], displayMath: [["\[", "\]"], ["@@", "@@"]] }, "options": { "enableMenu": false }'
{{< /multiconfig >}}

### Loading an External Version of the MathJax Library

{{% badge style="option" %}}Option{{% /badge %}} {{% badge style="frontmatter" %}}Front Matter{{% /badge %}} The theme uses the shipped MathJax library by default.

In case you want do use a different version of the MathJax library but don't want to override the shipped version, you can set `customMathJaxURL` to the URL of the external MathJax library.

{{< multiconfig section=params >}}
customMathJaxURL = 'https://unpkg.com/mathjax/es5/tex-mml-chtml.js'
{{< /multiconfig >}}

### Force Loading of the MathJax Library

{{% badge style="option" %}}Option{{% /badge %}} {{% badge style="frontmatter" %}}Front Matter{{% /badge %}} The MathJax library will be loaded if the page contains a `math` shortcode, Markdown codefence or the partial is called from your templates.

You can force loading the MathJax library if you are using Passthrough syntax by setting `math=true`. If a shortcode, Markdown codefence or partial was called, the option has no effect. This must be set in case you are using the [Passthrough configuration](#passthrough-configuration) to render math.

Instead of `math=true` you can also use the alias `math.force=true`.

{{< multiconfig section=params >}}
math = true
{{< /multiconfig >}}

### Passthrough Configuration

You can use your math without enclosing it in a shortcode or Markdown codefence by using a [Passthrough configuration](https://gohugo.io/content-management/mathematics/#step-1)

{{< multiconfig file=hugo >}}
[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        enable = true
        [markup.goldmark.extensions.passthrough.delimiters]
          inline = [['\(', '\)'], ['$',  '$']]
          block  = [['\[', '\]'], ['$$', '$$']]
{{< /multiconfig >}}

In this case you have to [force load](#force-loading-of-the-mathjax-library) the MathJax library either in your `hugo.toml` or in your page's front matter as the theme doesn't know if math is used.

[See the example](#examples) 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.

Anyways your formulae still needs to be enclosed by `$` or `$$` with any of the other available syntax as well.

{{% multishortcode name="math" %}}
content: |
  $$\left|
  \begin{array}{cc}
  a & b \\
  c & d
  \end{array}\right|$$
{{% /multishortcode %}}

### Inline Math

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

{{% multishortcode name="math" formats="markdown-passthrough,shortcode,partial" format="Euclid already knew, %s is irrational." %}}
content: $\sqrt{2}$
{{% /multishortcode %}}

### Block Math with Right Alignment

With Passthrough syntax, only the [**content** parameter](#parameters) is available.

{{% multishortcode name="math" %}}
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)$$
{{% /multishortcode %}}

### Chemical Formulae

The MathJax library can also be used for chemical formulae.

{{% multishortcode name="math" %}}
content: |

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