Improve transform.ToMath examples

content/en/about/features.md

@@ -55,7 +55,7 @@ toc: true
 : Use fenced code blocks and Markdown render hooks to include diagrams in your content.
 
 [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]
 : 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.

content/en/content-management/formats.md

@@ -29,15 +29,18 @@ content/
 
 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
 
 ### Markdown
 
 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:
 
@@ -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.
 
 [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]
 : 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
 
 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
 
-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
 
 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:
 
@@ -79,6 +97,11 @@ The CLI flags passed to the Asciidoctor executable depend on configuration. You
 hugo --logLevel info
 ```
 
+[AsciiDoc]: https://asciidoc.org/
+[configure the AsciiDoc renderer]: /getting-started/configuration-markup/#asciidoc
+[configure asciidoc]: /getting-started/configuration-markup/#asciidoc
+
+
 ### 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.
@@ -89,6 +112,8 @@ Hugo passes these CLI flags when calling the Pandoc executable:
 --mathjax
 ```
 
+[Pandoc]: https://pandoc.org/
+
 ### 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.
@@ -99,6 +124,9 @@ Hugo passes these CLI flags when calling the rst2html executable:
 --leave-comments --initial-header-level=2
 ```
 
+[Docutils]: https://docutils.sourceforge.io/
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
+
 ## Classification
 
 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
 
 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

content/en/content-management/mathematics.md

@@ -1,9 +1,9 @@
 ---
 title: Mathematics in Markdown
 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]
-keywords: [chemical,chemistry,latex,math,mathjax,tex,typesetting]
+keywords: [katex,latex,math,mathjax,typesetting]
 menu:
   docs:
     parent: content-management
@@ -15,37 +15,48 @@ math: true
 
 {{< new-in 0.122.0 >}}
 
+## Overview
+
+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, with this LaTeX markup:
+
+```text
 \[
 \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
-
-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].
-
-For example, this is the mathematical markup for the equations displayed at the top of this page:
+The MathJax display engine renders this:
 
-```text
 \[
 \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.
 
-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.
+
+{{% 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.
+
+[`transform.ToMath`]: /functions/transform/tomath/
+{{% /note %}}
+
+
+
 
 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.
 
 ## 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
 
@@ -122,7 +133,7 @@ The example above loads the partial template if you have set the `math` paramete
 
 ###### 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 >}}
 This is an inline \(a^*=x-b^*\) equation.
@@ -173,7 +184,7 @@ If you use the `$...$` delimiter pair for inline equations, and occasionally use
 
 ## 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 %}}
 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 +195,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:
 
 {{< code file=layouts/partials/math.html copy=true >}}
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected].9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
-<script defer src="https://cdn.jsdelivr.net/npm/[email protected].9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
-<script defer src="https://cdn.jsdelivr.net/npm/[email protected].9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected].11/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
+<script defer src="https://cdn.jsdelivr.net/npm/[email protected].11/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/[email protected].11/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
 <script>
   document.addEventListener("DOMContentLoaded", function() {
     renderMathInElement(document.body, {
@@ -223,6 +234,5 @@ As shown in [Step 2] above, MathJax supports chemical equations without addition
 [Step 1]: #step-1
 [Step 2]: #step-2
 [Step 3]: #step-3
-[TeX]: https://en.wikipedia.org/wiki/TeX
 [Typora]: https://typora.io/
-[passthrough extension]: https://github.com/gohugoio/hugo-goldmark-extensions
+[passthrough extension]: /getting-started/configuration-markup/#passthrough