hugo-theme-relearn/exampleSite/content/shortcodes/math.en.md
2024-10-11 16:47:27 +02:00

7.4 KiB

+++ description = "Beautiful math and chemical formulae" frontmatter = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"] options = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"] title = "Math" +++

You can use pure Markdown for writing simple math expressions.

If this is not enough, the math shortcode helps you rendering math and chemical formulae using the MathJax library.

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

Usage

{{< tabs groupid="shortcode-parameter">}} {{% tab title="passthrough" %}}

$$\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)$$

{{% /tab %}} {{% tab title="codefence" %}}

```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)$$
```

{{% /tab %}} {{% tab title="shortcode" %}}

{{</* 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 */>}}

{{% /tab %}} {{% tab title="partial" %}}

{{ partial "shortcodes/math.html" (dict
  "page"    .
  "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)$$"
  "align"   "center"
)}}

{{% /tab %}} {{< /tabs >}}

Passthrough syntax is only available by further configuration and has limited features as it does not provide any of the below parameter. Nevertheless, it is widely available in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.

Parameter

Name Default Notes
align center The vertical alignment.

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

Settings

Providing Initialization Options for the MathJax Library

{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}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 for all allowed settings.

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

Example

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

Loading an External Version of the MathJax Library

{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}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.

Example

{{< multiconfig file=hugo >}} [params] customMathJaxURL = "https://unpkg.com/mathjax/es5/tex-mml-chtml.js" {{< /multiconfig >}}

Force Loading of the MathJax Library

{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The MathJax library will be loaded if the page contains a math shortcode or codefence.

You can force loading the MathJax library if no shortcode or codefence was used by setting math=true. If a shortcode or codefence was found, the option has no effect. This must be set in case you are using the passthrough configuration to render math.

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

Passthrough Configuration

{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can use your math without enclosing it in a shortcode or codefence by using a passthrough configuration

{{< 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 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 on how a passthrough configurations makes using math really easy.

Examples

Passthrough Block Math

With passthrough configuration enabled you can just drop your math without enclosing it by shortcodes or codefences but no other parameters are available.

In this case you have to force load the MathJax library by setting math=true either in your hugo.toml or in your page's front matter.

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

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

Passthrough Inline Math

The same usage restrictions as of the previous example apply here as well.

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, \sqrt{2} is irrational.

Codefence Block Math with Right Alignment

If you are using codefences, more parameter are available. Your formulae still needs to be enclosed by $ or $$ as delimiters respectively.

```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)$$
```
$$\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)$$

Shortcode Block Math with Right Alignment

You can also use shortcode syntax. Your formulae still needs to be enclosed by $ or $$ as delimiters respectively.

{{</* 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 */>}}

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

Chemical Formulae

The MathJax library can also be used for chemical formulae.

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