TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-13 16:19:37 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve transform.ToMath examples

Browse Source
This commit is contained in:
Joe Mooring 2025-01-18 18:38:33 -08:00 committed by GitHub
parent 586970df2c
commit 1d40a7f3b8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
7 changed files with 223 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
content/en/about/features.md
View File

@ -55,7 +55,7 @@ toc: true
: Use fenced code blocks and Markdown render hooks to include diagrams in your content. : Use fenced code blocks and Markdown render hooks to include diagrams in your content.
[Mathematics] [Mathematics]
: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. : Include mathematical equations and expressions in Markdown using LaTeX markup.
[Syntax highlighting] [Syntax highlighting]
: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles. : Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles.

57
content/en/content-management/formats.md
View File

@ -29,7 +29,10 @@ content/
Regardless of content format, all content must have [front matter], preferably including both `title` and `date`. Regardless of content format, all content must have [front matter], preferably including both `title` and `date`.
Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification](#classification) table below for a list of markup identifiers and recognized file extensions. Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification] table below for a list of markup identifiers and recognized file extensions.
[classification]: #classification
[front matter]: /content-management/front-matter/
## Formats ## Formats
@ -37,7 +40,7 @@ Hugo selects the content renderer based on the `markup` identifier in front matt
Create your content in [Markdown] preceded by front matter. Create your content in [Markdown] preceded by front matter.
Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can [configure Goldmark] in your site configuration. Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can configure Goldmark in your [site configuration][configure goldmark].
Hugo provides custom Markdown features including: Hugo provides custom Markdown features including:
@ -48,24 +51,39 @@ Hugo provides custom Markdown features including:
: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more. : Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
[Mathematics] [Mathematics]
: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. : Include mathematical equations and expressions in Markdown using LaTeX markup.
[Render hooks] [Render hooks]
: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element. : Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
[Attributes]: /content-management/markdown-attributes/
[CommonMark]: https://spec.commonmark.org/current/
[Extensions]: /getting-started/configuration-markup/#goldmark-extensions
[GitHub Flavored Markdown]: https://github.github.com/gfm/
[Goldmark]: https://github.com/yuin/goldmark
[Markdown]: https://daringfireball.net/projects/markdown/
[Mathematics]: /content-management/mathematics/
[Render hooks]: https://gohugo.io/render-hooks/introduction/
[configure goldmark]: /getting-started/configuration-markup/#goldmark
### HTML ### HTML
Create your content in [HTML] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element. Create your content in [HTML] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element.
[HTML]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content
### Emacs Org Mode ### Emacs Org Mode
Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details](/content-management/front-matter/#emacs-org-mode). Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details].
[details]: /content-management/front-matter/#emacs-org-mode
[Emacs Org Mode]: https://orgmode.org/
### AsciiDoc ### AsciiDoc
Create your content in the [AsciiDoc] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to use the AsciiDoc content format. Create your content in the [AsciiDoc] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to use the AsciiDoc content format.
You can [configure the AsciiDoc renderer] in your site configuration. You can configure the AsciiDoc renderer in your [site configuration][configure asciidoc].
In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable: In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable:
@ -79,6 +97,11 @@ The CLI flags passed to the Asciidoctor executable depend on configuration. You
hugo --logLevel info hugo --logLevel info
``` ```
[AsciiDoc]: https://asciidoc.org/
[configure the AsciiDoc renderer]: /getting-started/configuration-markup/#asciidoc
[configure asciidoc]: /getting-started/configuration-markup/#asciidoc
### Pandoc ### Pandoc
Create your content in the [Pandoc] format preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to use the Pandoc content format. Create your content in the [Pandoc] format preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to use the Pandoc content format.
@ -89,6 +112,8 @@ Hugo passes these CLI flags when calling the Pandoc executable:
--mathjax --mathjax
``` ```
[Pandoc]: https://pandoc.org/
### reStructuredText ### reStructuredText
Create your content in the [reStructuredText] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils], specifically rst2html. You must install Docutils and its dependencies (Python) to use the reStructuredText content format. Create your content in the [reStructuredText] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils], specifically rst2html. You must install Docutils and its dependencies (Python) to use the reStructuredText content format.
@ -99,6 +124,9 @@ Hugo passes these CLI flags when calling the rst2html executable:
--leave-comments --initial-header-level=2 --leave-comments --initial-header-level=2
``` ```
[Docutils]: https://docutils.sourceforge.io/
[reStructuredText]: https://docutils.sourceforge.io/rst.html
## Classification ## Classification
Content format|Media type|Identifier|File extensions Content format|Media type|Identifier|File extensions
@ -116,22 +144,3 @@ When converting content to HTML, Hugo uses:
- External renderers for AsciiDoc, Pandoc, and reStructuredText - External renderers for AsciiDoc, Pandoc, and reStructuredText
Native renderers are faster than external renderers. Native renderers are faster than external renderers.
[AsciiDoc]: https://asciidoc.org/
[Asciidoctor]: https://asciidoctor.org/
[Attributes]: /content-management/markdown-attributes/
[CommonMark]: https://spec.commonmark.org/current/
[Docutils]: https://docutils.sourceforge.io/
[Emacs Org Mode]: https://orgmode.org/
[Extensions]: /getting-started/configuration-markup/#goldmark-extensions
[GitHub Flavored Markdown]: https://github.github.com/gfm/
[Goldmark]: https://github.com/yuin/goldmark
[HTML]: https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/HTML_basics
[Markdown]: https://daringfireball.net/projects/markdown/
[Mathematics]: /content-management/mathematics/
[Pandoc]: https://pandoc.org/
[Render hooks]: https://gohugo.io/render-hooks/introduction/
[configure Goldmark]: /getting-started/configuration-markup/#goldmark
[configure the AsciiDoc renderer]: /getting-started/configuration-markup/#asciidoc
[front matter]: /content-management/front-matter/
[reStructuredText]: https://docutils.sourceforge.io/rst.html

52
content/en/content-management/mathematics.md
View File

@ -1,9 +1,9 @@
--- ---
title: Mathematics in Markdown title: Mathematics in Markdown
linkTitle: Mathematics linkTitle: Mathematics
description: Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax. description: Include mathematical equations and expressions in Markdown using LaTeX markup.
categories: [content management] categories: [content management]
keywords: [chemical,chemistry,latex,math,mathjax,tex,typesetting] keywords: [katex,latex,math,mathjax,typesetting]
menu: menu:
docs: docs:
parent: content-management parent: content-management
@ -15,18 +15,11 @@ math: true
{{< new-in 0.122.0 >}} {{< new-in 0.122.0 >}}
\[
\begin{aligned}
KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
\end{aligned}
\]
## Overview ## Overview
Mathematical equations and expressions authored in [LaTeX] or [TeX] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax] or [KaTeX]. Mathematical equations and expressions written in [LaTeX] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax] or [KaTeX].
For example, this is the mathematical markup for the equations displayed at the top of this page: For example, with this LaTeX markup:
```text ```text
\[ \[
@ -37,15 +30,30 @@ JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y
\] \]
``` ```
The MathJax display engine renders this:
\[
\begin{aligned}
KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
\end{aligned}
\]
Equations and expressions can be displayed inline with other text, or as standalone blocks. Block presentation is also known as "display" mode. Equations and expressions can be displayed inline with other text, or as standalone blocks. Block presentation is also known as "display" mode.
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. Common delimiter pairs are shown in [Step 1]. 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.
The approach described below avoids reliance on platform-specific features like shortcodes or code block render hooks. Instead, it utilizes a standardized markup format for mathematical equations and expressions, compatible with the rendering engines used by GitHub, GitLab, [Microsoft VS Code], [Obsidian], [Typora], and others. {{% 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 while building your site with the [`transform.ToMath`]function.
The first approach is described below.
[`transform.ToMath`]: /functions/transform/tomath/
{{% /note %}}
## Setup ## Setup
Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax. Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX markup.
###### Step 1 ###### Step 1
@ -122,7 +130,7 @@ The example above loads the partial template if you have set the `math` paramete
###### Step 4 ###### Step 4
Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax. Include mathematical equations and expressions in Markdown using LaTeX markup.
{{< code file=content/math-examples.md copy=true >}} {{< code file=content/math-examples.md copy=true >}}
This is an inline \(a^*=x-b^*\) equation. This is an inline \(a^*=x-b^*\) equation.
@ -173,7 +181,7 @@ If you use the `$...$` delimiter pair for inline equations, and occasionally use
## Engines ## 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.9. 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 %}} {{% 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). 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).
@ -184,9 +192,9 @@ See the [inline delimiters](#inline-delimiters) section for details.
To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this: To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this:
{{< code file=layouts/partials/math.html copy=true >}} {{< code file=layouts/partials/math.html copy=true >}}
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous"> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script> <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script> <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
<script> <script>
document.addEventListener("DOMContentLoaded", function() { document.addEventListener("DOMContentLoaded", function() {
renderMathInElement(document.body, { renderMathInElement(document.body, {
@ -218,11 +226,7 @@ As shown in [Step 2] above, MathJax supports chemical equations without addition
[KaTeX]: https://katex.org/ [KaTeX]: https://katex.org/
[LaTeX]: https://www.latex-project.org/ [LaTeX]: https://www.latex-project.org/
[MathJax]: https://www.mathjax.org/ [MathJax]: https://www.mathjax.org/
[Microsoft VS Code]: https://code.visualstudio.com/
[Obsidian]: https://obsidian.md/
[Step 1]: #step-1 [Step 1]: #step-1
[Step 2]: #step-2 [Step 2]: #step-2
[Step 3]: #step-3 [Step 3]: #step-3
[TeX]: https://en.wikipedia.org/wiki/TeX [passthrough extension]: /getting-started/configuration-markup/#passthrough
[Typora]: https://typora.io/
[passthrough extension]: https://github.com/gohugoio/hugo-goldmark-extensions

215
content/en/functions/transform/ToMath.md
View File

@ -1,112 +1,165 @@
--- ---
title: transform.ToMath title: transform.ToMath
description: Renders a math expression using KaTeX. description: Renders mathematical equations and expressions written in the LaTeX markup language.
categories: [] categories: []
keywords: [math,katex] keywords: [katex,latex,math,typesetting]
action: action:
aliases: [] aliases: []
related: related:
- content-management/mathematics - content-management/mathematics
returnType: types.Result[template.HTML] returnType: types.Result[template.HTML]
signatures: ['transform.ToMath EXPRESSION [OPTIONS]'] signatures: ['transform.ToMath INPUT [OPTIONS]']
aliases: [/functions/tomath] aliases: [/functions/tomath]
toc: true toc: true
--- ---
{{< new-in "0.132.0" >}} {{< new-in "0.132.0" >}}
{{% note %}} 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 feature was introduced in Hugo 0.132.0 and is marked as experimental.
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. [KaTeX]: https://katex.org/
{{% /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
```go-html-template ```go-html-template
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }} {{ 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 ```go-html-template
{{ $macros := dict {{ $opts := dict "output" "htmlAndMathml" }}
"\\addBar" "\\bar{#1}" {{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" $opts }}
"\\bold" "\\mathbf{#1}"
}}
{{ $opts := dict "macros" $macros }}
{{ transform.ToMath "\\addBar{y} + \\bold{H}" $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 `{}`.
{{% comment %}}Indent to prevent splitting the description list.{{% / comment %}}
```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`.
{{% comment %}}Indent to prevent splitting the description list.{{% / comment %}}
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 ## 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. Let KaTeX throw an error and fail the build. This is the default behavior.
1. Handle the error in your template. See the render hook example below.
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. 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 >}} The example below demonstrates error handing within a template.
{{ with try (transform.ToMath .Inner) }}
{{ with .Err }} ## Example
{{ errorf "Failed to render KaTeX: %q. See %s" . $.Position }}
{{ else }} Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the `transform.ToMath` function.
{{ .Value }}
{{ end }} ###### Step 1
{{ end }}
{{- /* chomp trailing newline */ -}} 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 >}} {{< /code >}}
[error handling]: #error-handling ###### Step 3
[KaTeX options]: https://katex.org/docs/options.html
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color 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 {{% gl noop %}} 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 >}}

2
content/en/getting-started/configuration-markup.md
View File

@ -126,7 +126,7 @@ enable = true
{{< new-in 0.122.0 >}} {{< new-in 0.122.0 >}}
Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. See [mathematics in Markdown] for details. Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details.
[mathematics in Markdown]: content-management/mathematics/ [mathematics in Markdown]: content-management/mathematics/

36
content/en/render-hooks/passthrough.md
View File

@ -45,13 +45,11 @@ inline = [['\(', '\)']]
In the example above there are two sets of `block` delimiters. You may use either one in your Markdown. In the example above there are two sets of `block` delimiters. You may use either one in your Markdown.
The Goldmark passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in [LaTeX] or [Tex]. The Goldmark passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in the LaTeX markup language.
[mathematical expressions]: /content-management/mathematics/ [mathematical expressions]: /content-management/mathematics/
[LaTeX]: https://www.latex-project.org/
[Tex]: https://en.wikipedia.org/wiki/TeX
To enable custom rendering of passthrough elements, create a render hook. To enable custom rendering of passthrough elements, create a passthrough render hook.
## Context ## Context
@ -99,19 +97,35 @@ Hugo populates the `Attributes` map for _block_ passthrough elements. Markdown a
## Example ## Example
As an alternative to rendering mathematical expressions with the MathJax or KaTeX display engine, create a passthrough render hook which calls the [`transform.ToMath`] function: Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the [`transform.ToMath`] function.
[`transform.ToMath`]: /functions/transform/tomath/ [`transform.ToMath`]: /functions/transform/tomath/
{{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}} {{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}}
{{ if eq .Type "block" }} {{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{ $opts := dict "displayMode" true }} {{- with try (transform.ToMath .Inner $opts) }}
{{ transform.ToMath .Inner $opts }} {{- with .Err }}
{{ else }} {{ 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 }}
{{ transform.ToMath .Inner }} {{- else }}
{{ end }} {{- .Value }}
{{- $.Page.Store.Set "hasMath" true }}
{{- end }}
{{- end -}}
{{< /code >}} {{< /code >}}
Then, 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 {{% gl noop %}} statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
Although you can use one template with conditional logic as shown above, you can also create separate templates for each [`Type`](#type) of passthrough element: Although you can use one template with conditional logic as shown above, you can also create separate templates for each [`Type`](#type) of passthrough element:
```text ```text

2
content/en/tools/search.md
View File

@ -43,7 +43,7 @@ A static website with a dynamic search function? Yes, Hugo provides an alternati
[Hugo Lyra](https://github.com/paolomainardi/hugo-lyra) [Hugo Lyra](https://github.com/paolomainardi/hugo-lyra)
: Hugo-Lyra is a JavaScript module to integrate [Lyra](https://github.com/LyraSearch/lyra) into a Hugo website. It contains the server-side part to generate the index and the client-side library (optional) to bootstrap the search engine easily. : Hugo-Lyra is a JavaScript module to integrate [Lyra](https://github.com/LyraSearch/lyra) into a Hugo website. It contains the server-side part to generate the index and the client-side library (optional) to bootstrap the search engine easily.
[INFINI Pizza for WebAssembly](https://github.com/infinilabs/pizza-docsearch) [INFINI Pizza for WebAssembly](https://github.com/infinilabs/pizza-docsearch)
: Pizza is a super-lightweight yet fully featured search engine written in Rust. You can quickly add offline search functionality to your Hugo website in just five minutes with only three lines of code. For a step-by-step guide on integrating it with Hugo, check out [this blog tutorial](https://dev.to/medcl/adding-search-functionality-to-a-hugo-static-site-based-on-infini-pizza-for-webassembly-4h5e). : Pizza is a super-lightweight yet fully featured search engine written in Rust. You can quickly add offline search functionality to your Hugo website in just five minutes with only three lines of code. For a step-by-step guide on integrating it with Hugo, check out [this blog tutorial](https://dev.to/medcl/adding-search-functionality-to-a-hugo-static-site-based-on-infini-pizza-for-webassembly-4h5e).