mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-28 22:19:59 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
parent 208a0de6c3 5be51ac3db
commit 653f1c1d46
987 changed files with 12379 additions and 14083 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
docs/content/en/content-management/mathematics.md
View File

@@ -2,15 +2,8 @@
title: Mathematics in Markdown
linkTitle: Mathematics
description: Include mathematical equations and expressions in Markdown using LaTeX markup.
categories: [content management]
keywords: [katex,latex,math,mathjax,typesetting]
menu:
docs:
parent: content-management
weight: 270
weight: 270
toc: true
math: true
categories: []
keywords: []
---
{{< new-in 0.122.0 />}}
@@ -43,19 +36,16 @@ Equations and expressions can be displayed inline with other text, or as standal
Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different.
{{% note %}}
You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`] function while building your site.
The first approach is described below.
[`transform.ToMath`]: /functions/transform/tomath/
{{% /note %}}
> [!note]
> You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`] function while building your site.
>
> The first approach is described below.
## Setup
Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX markup.
###### Step 1
### 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.
@@ -73,11 +63,10 @@ math = true
The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3].
{{% note %}}
The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
See the [inline delimiters](#inline-delimiters) section for details.
{{% /note %}}
> [!note]
> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
>
> See the [inline delimiters](#inline-delimiters) section for details.
To disable passthrough of inline snippets, omit the `inline` key from the configuration:
@@ -94,11 +83,11 @@ block = [['@@', '@@']]
inline = [['@', '@']]
{{< /code-toggle >}}
###### Step 2
### Step 2
Create a partial template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section.
{{< code file=layouts/partials/math.html copy=true >}}
```go-html-template {file="layouts/partials/math.html" copy=true}
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
<script>
MathJax = {
@@ -111,15 +100,15 @@ Create a partial template to load MathJax or KaTeX. The example below loads Math
},
};
</script>
{{< /code >}}
```
The delimiters above must match the delimiters in your site configuration.
###### Step 3
### Step 3
Conditionally call the partial template from the base template.
{{< code file=layouts/_default/baseof.html >}}
```go-html-template {file="layouts/_default/baseof.html"}
<head>
...
{{ if .Param "math" }}
@@ -127,15 +116,15 @@ Conditionally call the partial template from the base template.
{{ end }}
...
</head>
{{< /code >}}
```
The example above loads the partial template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration.
###### Step 4
### Step 4
Include mathematical equations and expressions in Markdown using LaTeX markup.
{{< code file=content/math-examples.md copy=true >}}
```text {file="content/math-examples.md" copy=true}
This is an inline \(a^*=x-b^*\) equation.
These are block equations:
@@ -157,7 +146,7 @@ $$ a^*=x-b^* $$
$$
a^*=x-b^*
$$
{{< /code >}}
```
If you set the `math` parameter to `false` in your site configuration, you must set the `math` parameter to `true` in front matter. For example:
@@ -178,23 +167,21 @@ If you add the `$...$` delimiter pair to your configuration and JavaScript, you
A \\$5 bill _saved_ is a \\$5 bill _earned_.
```
{{% note %}}
If you use the `$...$` delimiter pair for inline equations, and occasionally use the&nbsp;`$`&nbsp;symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
{{% /note %}}
> [!note]
> If you use the `$...$` delimiter pair for inline equations, and occasionally use the&nbsp;`$`&nbsp;symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
## Engines
MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.11.
{{% note %}}
If you use the `$...$` delimiter pair for inline equations, and occasionally use the&nbsp;`$`&nbsp;symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
See the [inline delimiters](#inline-delimiters) section for details.
{{% /note %}}
> [!note]
> If you use the `$...$` delimiter pair for inline equations, and occasionally use the&nbsp;`$`&nbsp;symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
>
>See the [inline delimiters](#inline-delimiters) section for details.
To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this:
{{< code file=layouts/partials/math.html copy=true >}}
```go-html-template {file="layouts/partials/math.html" copy=true}
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css"
@@ -226,7 +213,7 @@ To use KaTeX instead of MathJax, replace the partial template from [Step 2] with
});
});
</script>
{{< /code >}}
```
The delimiters above must match the delimiters in your site configuration.
@@ -242,10 +229,10 @@ $$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
As shown in [Step 2] above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs).
[`transform.ToMath`]: /functions/transform/tomath/
[KaTeX]: https://katex.org/
[LaTeX]: https://www.latex-project.org/
[MathJax]: https://www.mathjax.org/
[Step 1]: #step-1
[passthrough extension]: /configuration/markup/#passthrough
[Step 2]: #step-2
[Step 3]: #step-3
[passthrough extension]: /getting-started/configuration-markup/#passthrough