mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-21 21:35:28 +02:00
Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'
This commit is contained in:
Bjørn Erik Pedersen
@@ -2,35 +2,27 @@
|
||||
title: transform.ToMath
|
||||
description: Renders mathematical equations and expressions written in the LaTeX markup language.
|
||||
categories: []
|
||||
keywords: [katex,latex,math,typesetting]
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- content-management/mathematics
|
||||
returnType: types.Result[template.HTML]
|
||||
signatures: ['transform.ToMath INPUT [OPTIONS]']
|
||||
keywords: []
|
||||
params:
|
||||
functions_and_methods:
|
||||
aliases: []
|
||||
returnType: types.Result[template.HTML]
|
||||
signatures: ['transform.ToMath INPUT [OPTIONS]']
|
||||
aliases: [/functions/tomath]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< new-in 0.132.0 />}}
|
||||
|
||||
Hugo uses an embedded instance of the [KaTeX] display engine to render mathematical markup to HTML. You do not need to install the KaTeX display engine.
|
||||
|
||||
[KaTeX]: https://katex.org/
|
||||
|
||||
```go-html-template
|
||||
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result.
|
||||
|
||||
[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML
|
||||
|
||||
To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet.
|
||||
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result.
|
||||
>
|
||||
> To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet.
|
||||
|
||||
```go-html-template
|
||||
{{ $opts := dict "output" "htmlAndMathml" }}
|
||||
@@ -41,18 +33,14 @@ To optimize rendering quality and accessibility, use the `htmlAndMathml` output
|
||||
|
||||
Pass a map of options as the second argument to the `transform.ToMath` function. The options below are a subset of the KaTeX [rendering options].
|
||||
|
||||
[rendering options]: https://katex.org/docs/options.html
|
||||
|
||||
displayMode
|
||||
: (`bool`) If `true` render in display mode, else render in inline mode. Default is `false`.
|
||||
: (`bool`) Whether to render in display mode instead of inline mode. Default is `false`.
|
||||
|
||||
errorColor
|
||||
: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
|
||||
|
||||
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
|
||||
|
||||
fleqn
|
||||
: (`bool`) If `true` render flush left with a 2em left margin. Default is `false`.
|
||||
: (`bool`) Whether to render flush left with a 2em left margin. Default is `false`.
|
||||
|
||||
macros
|
||||
: (`map`) A map of macros to be used in the math expression. Default is `{}`.
|
||||
@@ -78,7 +66,7 @@ output
|
||||
<link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
|
||||
|
||||
throwOnError
|
||||
: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`.
|
||||
: (`bool`) Whether to throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`.
|
||||
|
||||
## Error handling
|
||||
|
||||
@@ -94,12 +82,10 @@ The example below demonstrates error handing within a template.
|
||||
|
||||
Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the `transform.ToMath` function.
|
||||
|
||||
###### 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.
|
||||
|
||||
[passthrough extension]: /getting-started/configuration-markup/#passthrough
|
||||
|
||||
{{< code-toggle file=hugo copy=true >}}
|
||||
[markup.goldmark.extensions.passthrough]
|
||||
enable = true
|
||||
@@ -109,48 +95,45 @@ block = [['\[', '\]'], ['$$', '$$']]
|
||||
inline = [['\(', '\)']]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{% note %}}
|
||||
The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
|
||||
{{% /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, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
|
||||
|
||||
###### Step 2
|
||||
### Step 2
|
||||
|
||||
Create a [passthrough render hook] to capture and render the LaTeX markup.
|
||||
|
||||
[passthrough render hook]: /render-hooks/passthrough/
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-passthrough.html" copy=true}
|
||||
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
|
||||
{{- with try (transform.ToMath .Inner $opts) }}
|
||||
{{- with .Err }}
|
||||
{{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
|
||||
{{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
|
||||
{{- else }}
|
||||
{{- .Value }}
|
||||
{{- $.Page.Store.Set "hasMath" true }}
|
||||
{{- end }}
|
||||
{{- end -}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
###### Step 3
|
||||
### Step 3
|
||||
|
||||
In your base template, conditionally include the KaTeX CSS within the head element.
|
||||
|
||||
{{< code file=layouts/_default/baseof.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/baseof.html" copy=true}
|
||||
<head>
|
||||
{{ $noop := .WordCount }}
|
||||
{{ if .Page.Store.Get "hasMath" }}
|
||||
<link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
|
||||
{{ end }}
|
||||
</head>
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
|
||||
|
||||
#### Step 4
|
||||
### Step 4
|
||||
|
||||
Add some mathematical markup to your content, then test.
|
||||
|
||||
{{< code file=content/example.md >}}
|
||||
```text {file="content/example.md"}
|
||||
This is an inline \(a^*=x-b^*\) equation.
|
||||
|
||||
These are block equations:
|
||||
@@ -158,4 +141,24 @@ These are block equations:
|
||||
\[a^*=x-b^*\]
|
||||
|
||||
$$a^*=x-b^*$$
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
## Chemistry
|
||||
|
||||
{{< new-in 0.144.0 />}}
|
||||
|
||||
You can also use the `transform.ToMath` function to render chemical equations, leveraging the `\ce` and `\pu` functions from the [mhchem] package.
|
||||
|
||||
```text
|
||||
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
|
||||
```
|
||||
|
||||
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
|
||||
|
||||
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
|
||||
[KaTeX]: https://katex.org/
|
||||
[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML
|
||||
[mhchem]: https://mhchem.github.io/MathJax-mhchem/
|
||||
[passthrough extension]: /configuration/markup/#passthrough
|
||||
[passthrough render hook]: /render-hooks/passthrough/
|
||||
[rendering options]: https://katex.org/docs/options.html
|
||||
|
||||
Reference in New Issue
Block a user