mirror of
https://github.com/gohugoio/hugo.git
synced 2025-04-29 07:00:31 +03:00
Merge commit '346b60358d'
This commit is contained in:
Bjørn Erik Pedersen
commit
43307b07f8
384 changed files with 3305 additions and 3271 deletions
|
|
@ -1,112 +1,161 @@
|
|||
---
|
||||
title: transform.ToMath
|
||||
description: Renders a math expression using KaTeX.
|
||||
description: Renders mathematical equations and expressions written in the LaTeX markup language.
|
||||
categories: []
|
||||
keywords: [math,katex]
|
||||
keywords: [katex,latex,math,typesetting]
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- content-management/mathematics
|
||||
returnType: types.Result[template.HTML]
|
||||
signatures: ['transform.ToMath EXPRESSION [OPTIONS]']
|
||||
signatures: ['transform.ToMath INPUT [OPTIONS]']
|
||||
aliases: [/functions/tomath]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< new-in "0.132.0" >}}
|
||||
|
||||
{{% note %}}
|
||||
This feature was introduced in Hugo 0.132.0 and is marked as experimental.
|
||||
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.
|
||||
|
||||
This does not mean that it's going to be removed, but this is our first use of WASI/Wasm in Hugo, and we need to see how it [works in the wild](https://github.com/gohugoio/hugo/issues/12736) before we can set it in stone.
|
||||
{{% /note %}}
|
||||
|
||||
## Arguments
|
||||
|
||||
EXPRESSION
|
||||
: The math expression to render using KaTeX.
|
||||
|
||||
OPTIONS
|
||||
: A map of zero or more options.
|
||||
|
||||
## Options
|
||||
|
||||
These are a subset of the [KaTeX options].
|
||||
|
||||
output
|
||||
: (`string`). Determines the markup language of the output. One of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
|
||||
|
||||
{{% comment %}}Indent to prevent splitting the description list.{{% / comment %}}
|
||||
|
||||
With `html` and `htmlAndMathml` you must include KaTeX CSS within the `head` element of your base template. For example:
|
||||
|
||||
```html
|
||||
<head>
|
||||
...
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
|
||||
...
|
||||
</head>
|
||||
```
|
||||
|
||||
displayMode
|
||||
: (`bool`) If `true` render in display mode, else render in inline mode. Default is `false`.
|
||||
|
||||
leqno
|
||||
: (`bool`) If `true` render with the equation numbers on the left. Default is `false`.
|
||||
|
||||
fleqn
|
||||
: (`bool`) If `true` render flush left with a 2em left margin. Default is `false`.
|
||||
|
||||
minRuleThickness
|
||||
: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
|
||||
|
||||
macros
|
||||
: (`map`) A map of macros to be used in the math expression. Default is `{}`.
|
||||
|
||||
throwOnError
|
||||
: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTex. See [error handling]. Default is `true`.
|
||||
|
||||
errorColor
|
||||
: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic
|
||||
[KaTeX]: https://katex.org/
|
||||
|
||||
```go-html-template
|
||||
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
|
||||
```
|
||||
|
||||
### Macros
|
||||
{{% 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 %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $macros := dict
|
||||
"\\addBar" "\\bar{#1}"
|
||||
"\\bold" "\\mathbf{#1}"
|
||||
}}
|
||||
{{ $opts := dict "macros" $macros }}
|
||||
{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
|
||||
{{ $opts := dict "output" "htmlAndMathml" }}
|
||||
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" $opts }}
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
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`.
|
||||
|
||||
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`.
|
||||
|
||||
macros
|
||||
: (`map`) A map of macros to be used in the math expression. Default is `{}`.
|
||||
|
||||
```go-html-template
|
||||
{{ $macros := dict
|
||||
"\\addBar" "\\bar{#1}"
|
||||
"\\bold" "\\mathbf{#1}"
|
||||
}}
|
||||
{{ $opts := dict "macros" $macros }}
|
||||
{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
|
||||
```
|
||||
|
||||
minRuleThickness
|
||||
: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
|
||||
|
||||
output
|
||||
: (`string`). Determines the markup language of the output, one of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
|
||||
|
||||
With `html` and `htmlAndMathml` you must include the KaTeX style sheet within the `head` element of your base template.
|
||||
|
||||
```html
|
||||
<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`.
|
||||
|
||||
## Error handling
|
||||
|
||||
There are 3 ways to handle errors from KaTeX:
|
||||
There are three ways to handle errors:
|
||||
|
||||
1. Let KaTeX throw an error and make the build fail. This is the default behavior.
|
||||
1. Handle the error in your template. See the render hook example below.
|
||||
1. Let KaTeX throw an error and fail the build. This is the default behavior.
|
||||
1. Set the `throwOnError` option to `false` to make KaTeX render the expression as an error instead of throwing an error. See [options](#options).
|
||||
1. Handle the error in your template.
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-passthrough-inline.html copy=true >}}
|
||||
{{ with transform.ToMath .Inner }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "Failed to render KaTeX: %q. See %s" . $.Position }}
|
||||
{{ else }}
|
||||
{{ . }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{- /* chomp trailing newline */ -}}
|
||||
The example below demonstrates error handing within a template.
|
||||
|
||||
## Example
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
[markup.goldmark.extensions.passthrough.delimiters]
|
||||
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 %}}
|
||||
|
||||
###### 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 >}}
|
||||
{{- $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 }}
|
||||
{{- else }}
|
||||
{{- .Value }}
|
||||
{{- $.Page.Store.Set "hasMath" true }}
|
||||
{{- end }}
|
||||
{{- end -}}
|
||||
{{< /code >}}
|
||||
|
||||
[error handling]: #error-handling
|
||||
[KaTeX options]: https://katex.org/docs/options.html
|
||||
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
|
||||
###### Step 3
|
||||
|
||||
In your base template, conditionally include the KaTeX CSS within the head element.
|
||||
|
||||
{{< code 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
|
||||
|
||||
Add some mathematical markup to your content, then test.
|
||||
|
||||
{{< code file=content/example.md >}}
|
||||
This is an inline \(a^*=x-b^*\) equation.
|
||||
|
||||
These are block equations:
|
||||
|
||||
\[a^*=x-b^*\]
|
||||
|
||||
$$a^*=x-b^*$$
|
||||
{{< /code >}}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue